Skip to content
Documentation

Getting started

BoringCache provides Cache, Artifacts, and Registry in one workspace. This guide covers CLI installation, repository setup, and your first cached build.

1. Installation and repository setup

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.

After creating an account or organization, choose a plan. Start a 30-day trial without a card, or subscribe to a paid plan, then create a workspace. In the workspace, choose Cache, Artifacts or Registry and enable its storage before uploading data. View plans and trial limits.

Install and onboard
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. Build tool integration

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. First build and cache 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.

Preview build activity →

Artifacts and Registry

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

Artifacts store immutable build outputs with explicit retention and verified downloads. Their lifecycle is 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.