Skip to content
Documentation

Docs / Adapter commands / Docker

Docker adapter

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.

Command
boringcache docker
Protocol
BuildKit type=boringcache backend
Action
mode: docker

How the adapter works

Shared layers by default

The managed type=boringcache backend carries BuildKit's cache graph and immutable layer bodies between CI runners and local builds.

Fresh execution when you need it

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.

Native tool cache inside Docker

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.

Set up Docker

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"

Before the first run

  • Install Docker with Buildx available.
  • Run boringcache onboard once. A root Dockerfile adds a local Docker build command; review it before committing .boringcache.toml. Configure another command for Buildx, Bake, Compose, or a Dockerfile in another directory.
  • Keep ordinary BuildKit layer reuse on unless the workload deliberately needs fresh instruction execution.

Configuration and cache behavior

One copy of tool outputs

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.

Share mounts across separate image graphs

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.

Two jobs can publish one 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.

Configure BuildKit with TOML

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.

Select another config file

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.

Apply native worker settings

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.

Keep file paths and connections explicit

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.

Build on another machine

Build on an existing SSH server

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.

Build on an existing SSH server
[remotes.build]
provider = "ssh"
host = "build.example.com"
user = "deploy"
default = true

Server requirements

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.

Build on a Namespace instance

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.

Build on a Namespace instance
[remotes.namespace]
provider = "namespace"
region = "us"
architecture = "amd64"
cpus = 8
memory-mb = 16384

Build on a Daytona sandbox

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.

Build on a Daytona sandbox
[remotes.daytona]
provider = "daytona"
region = "eu"
cpus = 8
memory-mb = 32768
disk-gb = 100

[remotes.daytona.worker]
timeout-seconds = 600

Images, cache tags and kept state

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.

Use REAPI tool caches inside Docker

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.

.boringcache.toml
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.

Use the same adapter in GitHub Actions

Docker mode runs the command committed under [adapters.docker], restores reusable layers, and lets trusted jobs publish new cache.

.github/workflows/ci.yml
- 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.

GitHub Actions reference

Benchmarks

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.

PostHog

Docker

Benchmark →

Product analytics platform. One Docker image with the Django backend and Node.js frontend.

Average restore, build and save · lower is better

GitHub runner

4 vCPU · 16 GB · Ubuntu 24.04 x86-64

Base · Image layers

BoringCache
15 min 2 s 30 builds
GHA Cache
28 min 22 s 30 builds
GHCR
20 min 58 s 30 builds

Plus · Image layers, tool caches and cache mounts

BoringCache +
18 min 1 s 30 builds
GHA Cache Dance
41 min 8 s 30 builds
Same CPU model

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.

GHA Cache vs BoringCache
1.96× · 10 of 30
GHCR vs BoringCache
1.39× · 7 of 30
GHA Cache Dance vs BoringCache +
2.32× · 11 of 30
6 CPU models recorded
BoringCache · Image layers
AMD EPYC 7763 (16 builds) · AMD EPYC 9V74 (10 builds) · AMD EPYC 9V45 (3 builds) · Intel Xeon Platinum 8370C (1 build)
BoringCache + · Image layers, tool caches and cache mounts
AMD EPYC 7763 (12 builds) · AMD EPYC 9V45 (8 builds) · AMD EPYC 9V74 (7 builds) · Intel Xeon Platinum 8573C (2 builds) · Intel Xeon Platinum 8370C (1 build)
GHA Cache · Buildx type=gha, mode=max
AMD EPYC 7763 (15 builds) · AMD EPYC 9V74 (8 builds) · AMD EPYC 9V45 (4 builds) · Intel Xeon Platinum 8573C (2 builds) · Intel Xeon 6973P-C (1 build)
GHCR · Buildx type=registry, mode=max
AMD EPYC 9V74 (13 builds) · AMD EPYC 7763 (9 builds) · AMD EPYC 9V45 (5 builds) · Intel Xeon Platinum 8370C (2 builds) · Intel Xeon Platinum 8573C (1 build)
GHA Cache Dance · type=gha, mode=max; cache mounts saved by actions/cache
AMD EPYC 7763 (18 builds) · AMD EPYC 9V74 (5 builds) · AMD EPYC 9V45 (2 builds) · Intel Xeon Platinum 8370C (2 builds) · Intel Xeon Platinum 8573C (2 builds) · Intel Xeon 6973P-C (1 build)
Cold and warm builds

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.

One cold and warm build per cache
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
One cold and warm build per cache
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

GitHub Arm runner

4 vCPU · 16 GB · Ubuntu 24.04 Arm64

Base · Image layers

BoringCache
11 min 57 s 30 builds
GHA Cache
21 min 19 s 30 builds
GHCR
16 min 10 s 30 builds

Plus · Image layers, tool caches and cache mounts

BoringCache +
15 min 22 s 30 builds
GHA Cache Dance
34 min 13 s 30 builds

Neoverse-N2

Cold and warm builds

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.

One cold and warm build per cache
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
One cold and warm build per cache
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

Cache hits

BoringCache · GitHub runner · 4 vCPU

98.5% of 2,486 lookups over 30 builds

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

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.