Documentation
Start with the build you already run.
BoringCache provides Cache, Artifacts, and Registry in one workspace. Install the CLI, connect your repository, and start with a cache integration.
1. Install and connect.
onboard authenticates the CLI, selects or creates the workspace, writes .boringcache.toml when it finds useful cache state, and keeps the same cache names across local runs, Docker builds, CI, and agent sandboxes.
curl -sSL https://install.boringcache.com/install.sh | sh cd your-project && boringcache onboard
Workflow setup is optional and skipped by default. Press Enter at the prompt, or run boringcache onboard --skip-workflows (-S), to leave workflow files untouched.
Installation and authentication →2. Choose your tool.
Use the native integration for your build system. Each setup shows the relevant configuration and command.
For a directory cache, use boringcache run with the entries in your repository configuration.
3. Run the build and inspect reuse.
On a new workspace, the first successful trusted run populates the cache. Run the same step from another compatible environment to see reuse.
Use your configured command, then inspect cache activity in the workspace. Add the same configuration to CI when you are ready.
GitHub Actions
Connect the workspace and add the native BoringCache Action.
Another CI system
Use the CLI on the runner and the authentication method that fits your CI.
Need something other than cache?
Setup reference.
Installation
Pick the install path that fits your environment, then run onboard once per repo.
Cloud agent sandboxes
Start Codex, Cursor, Claude, or another cloud sandbox with restored dependencies and build state, using a read-only token.
MCP for coding agents
Connect one read-only BoringCache server, choose the account it may use, and let your agent inspect recent runs and cache entries across enabled workspaces.
Organization SSO
Connect a SAML identity provider, link existing members, and require organization sign-in after testing recovery and credentials.
CLI
Run, save and restore, authenticate, then diagnose from Workspace status to an exact cache tag or entry.
Adapter commands
One command per supported tool: connect its native cache, run the build, and finish publication before the command exits.
Artifacts
Keep immutable build outputs with explicit retention, verified downloads, and a lifecycle separate from cache.
Publisher trust
Choose who may publish build data and verify the evidence available for Cache, Artifacts, and Registry.
GitHub Actions
Bring local BoringCache settings into GitHub Actions with short-lived workload identity, or choose separate scoped credentials when OIDC is unavailable.
Bring your own storage
Connect an S3-compatible bucket or Azure Blob container for Cache and Artifacts. Runners use short-lived object URLs.
Troubleshooting
Check setup, repo config, one adapter run, and access scope in a predictable order.
Concepts
Workspaces, tags and platform suffixes, content-addressed storage, and the security model.
Looking for how BoringCache fits a specific tool? The build cache pages explain what each tool can reuse.
Need help or found something unclear? Open an issue or browse the CLI repo.