Shared layers by default
The managed type=boringcache backend carries BuildKit's cache graph and immutable layer bodies between CI runners and local builds.
Getting started
On this page
j / k move between sections.
Docs / Adapter commands / Docker
Run Docker Buildx, Bake, or Compose with managed BuildKit cache. Keep the same build commands while reusable layers and selected build work move between machines.
The managed type=boringcache backend carries BuildKit's cache graph and immutable layer bodies between CI runners and local builds.
Opt-in --mount-cache persists RUN cache mounts independently of layer hits. Keep --no-cache or cache:false semantics while dependency and package-manager work remains reusable.
Opt-in tool cache composes sccache, ccache, Go, Bazel, Gradle, Maven, Nx, or Turbo with—or without—layer hits. Cargo uses mount cache for target and registry state plus sccache for compiler results.
Run boringcache onboard once, then use the Docker adapter from .boringcache.toml or wrap an explicit docker buildx build command. BuildKit still decides the cache graph; BoringCache supplies a cache backend with shared storage, proxy uploads, and run diagnostics.
workspace = "my-org/my-project" [adapters.docker] tag = "image-main" command = ["docker", "buildx", "build", "."] tool-cache = ["sccache"] mount-cache = true [adapters.sccache] tag = "rust-main"
.boringcache.toml. Configure another command for Buildx, Bake, Compose, or a Dockerfile in another directory.
With tool cache selected, ccache and sccache keep compiler outputs only in BoringCache, not in a local cache directory, so a --mount-cache archive does not store a second copy, and a read-only build downloads hits without uploading. The CLI applies the same rule to task outputs from Turbo 2.3.0 and later; a --cache flag on the turbo command overrides it. Turbo rejects the deprecated --no-cache, --remote-only and --remote-cache-read-only flags alongside this setting, so remove --remote-only and use --cache in place of the others.
With the next managed BuildKit image, Nx and Maven get a local cache directory that starts empty in each RUN step and is removed when the step ends, so neither the image layer nor a cache mount keeps a second copy, and TURBO_CACHE or NX_CACHE_DIRECTORY set in the Dockerfile takes precedence over the BoringCache value. A cache location set in the directory where boringcache runs keeps the tool's own directory: cacheDirectory in nx.json, or maven.build.cache.location in .mvn/maven.config or .mvn/jvm.config.
Until then, Nx and Maven still write their own local cache, so a cache mount over that directory stores a second copy.
One tag addresses the layer cache. Add --mount-namespace so two jobs that need their own image graphs can still share cache mounts: give each job its own tag and both the same namespace. A bare value covers every mount; MOUNT_ID=NAMESPACE addresses one --mount=type=cache id, so a shared registry can sit beside separate target directories. Mounts you do not name keep the tag's identity. Requires --mount-cache. Set it in .boringcache.toml as adapters.docker.mount-namespace.
A namespaced mount is shared on purpose, so publication combines rather than replaces. Before publishing, the job checks whether another job has published since its own restore; if so it merges the published files it does not already have, keeping its own copy of every shared path, and commits against the snapshot it merged. A job that loses that race merges again and retries instead of dropping its work. Deleted files are not propagated between jobs, so a namespace grows until its entry expires.
Place buildkitd.toml in the directory where you run the command or an ancestor within the repository. BoringCache uses the nearest file, stopping at the Git root. Outside Git it stops at the .boringcache.toml directory, or the invocation directory when no repo config exists. Without a file, the worker uses its defaults.
Use --buildkitd-config path/to/buildkitd.toml before --, or set buildkitd-config under [adapters.docker] in .boringcache.toml. The CLI flag wins over the repo setting and discovery. CLI paths are relative to the invocation directory; repo paths are relative to .boringcache.toml. A selected missing, unreadable, or invalid file fails the build. Config files must be regular files no larger than 1 MiB.
Use native BuildKit settings such as [worker.oci] max-parallelism = 1, registry mirrors, DNS, worker labels, and garbage-collection policies. Explicit TOML snapshotter and gc values take precedence over BoringCache defaults, including the snapshotter environment setting. Changed settings recreate the worker before the next build. max-parallelism limits concurrent build steps; BORINGCACHE_MANAGED_BUILDKIT_CPUS limits the worker container CPU quota and BORINGCACHE_MANAGED_BUILDKIT_CPUSET_CPUS selects host CPU IDs.
Registry CA and client keypair files are read relative to the selected TOML file and copied privately into the worker. Certificate changes also recreate it. Other paths refer to files inside the worker container. BoringCache manages /var/lib/buildkit, the OCI worker, and the local Docker connection; incompatible root, grpc.address, grpc.tls, or worker-enable settings fail clearly. Use the native TOML format without changing these managed settings.
Add a named remote to .boringcache.toml and pass --remote to the same boringcache docker or boringcache buildkit command. Buildx or buildctl keeps running on your machine and connects over SSH to a BuildKit daemon on the remote Linux server. The build context, secrets, SSH agent and local outputs stay on your machine and reach the build through the normal BuildKit session. Bake and Compose builds work the same way.
Remote builds need BoringCache CLI 1.45.0 or later. boringcache docker --remote -- docker buildx build . builds on the only configured remote, or on the one with default = true; --remote build selects a remote by name. --dry-run --json shows the plan without connecting. Cache restore, publication and read-only rules are the same as for a local build.
[remotes.build] provider = "ssh" host = "build.example.com" user = "deploy" default = true
boringcache doctor --remote NAME checks the configuration and credential source. Add --connect to prepare and inspect a worker; native providers allocate and delete compute and may charge for it. A real build is still needed to verify BuildKit startup, socket forwarding, cache access and exporters.
A Linux server you can reach with ssh, logged in as root or as a user with passwordless sudo. The server needs mount and PID namespaces, curl or wget, CA certificates, util-linux and network access to BoringCache. It does not need Docker. Its sshd must allow Unix socket forwarding, which OpenSSH allows by default.
BoringCache runs your OpenSSH with your configuration and known_hosts and never prompts; identity-file, known-hosts-file and port are optional settings on the remote. On first use the CLI installs its own release on the server and checks it against the release checksums. You create and remove the server yourself. BoringCache keeps its CLI, verified helper binaries and BuildKit state under /var/cache/boringcache and removes each build's temporary files when the build ends.
Set provider = "namespace" with a region, architecture and machine size. The CLI creates the instance, runs the build and deletes the instance afterwards. Provider credentials stay on your machine. Credentials are selected from NSC_TOKEN, NSC_TOKEN_FILE, the Namespace runner token file, then your existing nsc login or federation. Bearer token files are reread for each provider request. Session credentials require nsc. Invalid explicit credentials stop the attempt; they do not fall back to another account. The identity needs instance access, including creation, SSH and deletion.
If the CLI cannot confirm the deletion, it says so. The instance then stops at its provider deadline, which is the worker timeout plus 180 seconds.
[remotes.namespace] provider = "namespace" region = "us" architecture = "amd64" cpus = 8 memory-mb = 16384
The CLI accepts provider = "daytona" with a region and optional CPU, memory and disk settings. Set DAYTONA_API_KEY on your machine or in your CI secret store, then run the same boringcache docker --remote daytona or boringcache buildkit --remote daytona command. The CLI creates a fresh sandbox, builds over SSH and deletes the sandbox after completion, failure or handled cancellation. The API key stays on your machine.
Trust the SSH host key for ssh.app.daytona.io before the first build, using the known_hosts entry published in [Daytona’s security policy](https://github.com/daytona/.github/blob/main/SECURITY.md#ssh-host-key-verification). The CLI refuses unknown or changed keys. Set known-hosts-file on the remote if you keep the trusted key in a separate file. The temporary SSH token is held in a private file. The CLI removes that file on handled exit; SIGKILL or caller loss can leave it behind until you remove it. Sandbox deletion invalidates the token.
Set cpus, memory-mb and disk-gb in the named remote to request its compute shape without preparing a snapshot. Memory must be a whole number of GiB expressed in MiB, such as 32768 for 32 GiB. Unspecified values come from Daytona’s default template. With no sizing settings, the default template currently provides 2 vCPU, 4 GiB RAM and 8 GiB disk. Provider resource limits apply. For advanced environments, select an image available to Daytona, or use an existing fixed snapshot without sizing overrides. The environment needs Linux, root or passwordless sudo, mount and PID namespaces, and network access to BoringCache and its storage endpoints.
The CLI requests a hard expiry of the worker timeout plus 180 seconds for a fixed template, or plus 690 seconds for an image or resource profile, rounded up to whole minutes. It checks the confirmed sandbox and SSH expiry and rejects shorter account limits. This wall-clock lifetime includes sandbox startup, worker installation and local build planning; slow preparation can reduce the time available for the build. Idle stop and pause are disabled. The CLI confirms deletion and reports when cleanup remains unconfirmed. The expiry bounds the sandbox lifetime if your machine disconnects or the CLI is killed. No persistent volume or saved workspace is requested.
[remotes.daytona] provider = "daytona" region = "eu" cpus = 8 memory-mb = 32768 disk-gb = 100 [remotes.daytona.worker] timeout-seconds = 600
Use --publish-image to push the image from the server to the BoringCache Registry, or --load to load it into Docker on your machine, which downloads the whole image. With --publish-image, leave --tag out of the Docker command, because Buildx would push that name too.
Cache tags use the server's platform, for example ubuntu-24-amd64, so a remote build and a CI job on the same platform share cache. To share cache between a local build on a Mac and a remote build, pass the same Docker --platform, for example --platform linux/arm64, to both build commands.
The server keeps BuildKit state for each workspace and cache tag, so its next build skips cached steps without loading their layers. A build that starts while another build is using that state starts fresh and loads cached layers from BoringCache. Namespace instances and Daytona sandboxes always start fresh.
Remote builds run from macOS or Linux and use native BuildKit on the server. Set BORINGCACHE_RESTORE_TOKEN on your machine, and BORINGCACHE_SAVE_TOKEN for builds that write. Only those tokens reach the server; admin tokens, NSC_TOKEN and DAYTONA_API_KEY stay on your machine. Use servers dedicated to builds: other accounts on the server can reach the build's cache proxy while it runs.
The bazel-reapi, moon, pants, buck2, and sbt
selectors require CLI 1.40.0 or later. Check boringcache --version before using them.
In GitHub Actions, choose an Action release with a compatible default CLI.
Install the build tool in your image and keep its project configuration in the build context.
BoringCache supplies the cache connection and credentials to build commands; it does not provide remote execution.
Commit this example to .boringcache.toml, then run boringcache docker.
The image layer cache uses image-main; the Bazel REAPI cache uses the tag in [adapters.bazel-reapi].
Replace bazel-reapi in both places with another selector to cache that tool.
workspace = "my-org/my-project" [adapters.docker] tag = "image-main" command = ["docker", "buildx", "build", "."] tool-cache = ["bazel-reapi"] [adapters.bazel-reapi] tag = "bazel-build" read-only = true
This example restores Bazel results without publishing new ones. Set the tool's read-only to false
when the job may publish. boringcache docker --read-only makes both the layer cache and all selected tool caches read-only.
For one run, boringcache docker --tool-cache bazel-reapi:another-tag selects an explicit tag instead of the adapter's configured tag.
For docker buildx bake or supported docker compose build commands,
add tool-cache-target = ["app"] under [adapters.docker] to apply tool caching only to the named Bake target or Compose service.
The equivalent flag is --tool-cache-target app. This selects a build target or service, not a Dockerfile stage.
Without it, tool caching applies to all resolved targets. It is not supported with docker buildx build.
Select bazel for the HTTP remote cache or bazel-reapi for gRPC REAPI.
They use separate cache namespaces, and one build cannot select both.
Each tool retains the version requirements, options, and output limitations in its guide:
Bazel REAPI
, Moon
, Pants
, Buck2
, sbt 2.
Docker mode runs the command committed under [adapters.docker], restores reusable layers, and lets trusted jobs publish new cache.
- uses: boringcache/one@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2 with: trust-policy: auto mode: docker
Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.
Chroma, Discourse, Hugo, Immich, llama.cpp, Mastodon, n8n, n8n distroless runners, n8n task runners, PostHog, and Qdrant build the same upstream commits with BoringCache, GHA Cache, GHCR and GHA Cache Dance on the same runner classes.
Docker
Benchmark →Product analytics platform. One Docker image with the Django backend and Node.js frontend.
Average restore, build and save · lower is better
4 vCPU · 16 GB · Ubuntu 24.04 x86-64
Base · Image layers
Plus · Image layers, tool caches and cache mounts
Builds of one commit can land on different CPU models. These ratios use only the build pairs where both caches ran on the same model; above 1.00× means BoringCache's total time over those pairs was lower.
Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| Base · Image layers | |||
| BoringCache Image layers | 15 min 28 s | 2 min 13 s | Cold: AMD EPYC 7763 · Warm: AMD EPYC 9V74 |
| Plus · Image layers, tool caches and cache mounts | |||
| BoringCache + Image layers, tool caches and cache mounts | 16 min 29 s | 3 min 4 s | Cold: AMD EPYC 7763 · Warm: Intel Xeon Platinum 8573C |
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| GHA Cache Buildx type=gha, mode=max | 39 min 59 s | 3 min 6 s | Cold: AMD EPYC 7763 · Warm: AMD EPYC 9V74 |
| GHCR Buildx type=registry, mode=max | 23 min 24 s | 2 min 44 s | AMD EPYC 7763 |
4 vCPU · 16 GB · Ubuntu 24.04 Arm64
Base · Image layers
Plus · Image layers, tool caches and cache mounts
Neoverse-N2
Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| Base · Image layers | |||
| BoringCache Image layers | 12 min 51 s | 2 min 20 s | Neoverse-N2 |
| Plus · Image layers, tool caches and cache mounts | |||
| BoringCache + Image layers, tool caches and cache mounts | 12 min 32 s | 2 min 18 s | Neoverse-N2 |
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| GHA Cache Buildx type=gha, mode=max | 26 min 41 s | 2 min 39 s | Neoverse-N2 |
| GHCR Buildx type=registry, mode=max | 16 min 37 s | 2 min 15 s | Neoverse-N2 |
4 vCPU · 16 GB · Ubuntu 24.04 x86-64
Base · Image layers
Plus · Image layers, tool caches and cache mounts
Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| Base · Image layers | |||
| BoringCache Image layers | 12 min 27 s | 61.1 s | AMD EPYC 9R45 |
| Plus · Image layers, tool caches and cache mounts | |||
| BoringCache + Image layers, tool caches and cache mounts | 10 min 57 s | 59.7 s | AMD EPYC 9R45 |
8 vCPU · 32 GB · Ubuntu 24.04 x86-64
Base · Image layers
Plus · Image layers, tool caches and cache mounts
AMD EPYC 9R45
Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| Base · Image layers | |||
| BoringCache Image layers | 5 min 4 s | 47.3 s | AMD EPYC 9R45 |
| Plus · Image layers, tool caches and cache mounts | |||
| BoringCache + Image layers, tool caches and cache mounts | 5 min 33 s | 52.0 s | AMD EPYC 9R45 |
16 vCPU · 32 GB* · x86-64
Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| Depot builder Builds on Depot's remote BuildKit machine | 6 min 46 s | 2 min 10 s | Not recorded |
* Builder sizes published by providers.
4 vCPU · 16 GB · x86-64
Base · Image layers
Plus · Image layers, tool caches and cache mounts
AMD EPYC
Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| Base · Image layers | |||
| BoringCache Image layers | 7 min 32 s | 44.8 s | AMD EPYC |
| Plus · Image layers, tool caches and cache mounts | |||
| BoringCache + Image layers, tool caches and cache mounts | 9 min 21 s | 52.9 s | AMD EPYC |
8 vCPU · 16 GiB* · x86-64
Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.
| Cache | Cold | Warm | CPU |
|---|---|---|---|
| Namespace builder Builds on Namespace's remote BuildKit machine | 8 min 27 s | 3 min 51 s | Not recorded |
* Builder sizes published by providers.
BoringCache · GitHub runner · 4 vCPU
98.5% of 2,486 lookups over 30 builds
Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.
Compare every supported command, protocol, and Action mode in one place.
Adapter command index →Need help or found something unclear? Open an issue or browse the CLI repo.
We use cookies to understand how people use BoringCache. Privacy policy