BoringCache Build Tool Adapters

Choose an adapter

Use an adapter when the build tool already has a native remote cache. The command connects the tool, runs or prepares the build, and finishes cache writes before it exits.

Use boringcache run for directory and dependency archives. Use the named command below for a native tool protocol.

Docker

boringcache docker

BuildKit type=boringcache backend

BuildKit

boringcache buildkit

BuildKit cache import and export through the managed type=boringcache backend

Bazel

boringcache bazel

Bazel HTTP remote cache over /ac/* and /cas/*

Cargo

boringcache cargo

Cargo target-state reuse plus sccache-backed compiler cache

ccache

boringcache ccache

ccache HTTP remote storage through a local helper

Go

boringcache go

Go GOCACHEPROG over /gocache/*

Gradle

boringcache gradle

Gradle HTTP build cache over /cache/*

GitHub Actions compatibility

boringcache gha

GitHub Actions Cache v2 and ArtifactService on the job's standard results-service environment

Maven

boringcache maven

Maven build cache extension over /v1.1/* and /v1/*

Nix

boringcache nix

Nix HTTP binary cache with substituter and post-build publication

Nx

boringcache nx

Nx self-hosted remote cache over /v1/cache/*

sccache

boringcache sccache

sccache WebDAV-style cache paths

Turborepo

boringcache turbo

Turborepo Remote Cache API over /v8/artifacts/*

Xcode

boringcache xcode

Xcode compilation cache over Apple's content-addressable store

Configure an adapter once

Keep workspace, cache tag, command, scope, and stable labels in .boringcache.toml. The same command then works from a local shell, another CI provider, or boringcache/one.

.boringcache.toml

workspace = "my-org/my-project"

[proxy]
metadata-hints = ["project=web"]

[adapters.turbo]
tag = "turbo-main"
command = ["pnpm", "turbo", "run", "build"]
metadata-hints = ["tool=turborepo", "lane=ci"]

boringcache turbo

Save your repo setup: keep the repeatable command and cache identity in source control.

Change one run: use command-line flags for a deliberate one-off override.

Use one adapter per command: run separate commands or Action steps when a job needs more than one native cache.

Publish Docker images

Build and publish in one BuildKit solve, or publish an image already present in the local Docker engine. Image storage is independent from the build cache.

Build and publish

boringcache docker --publish-image web:$GITHUB_SHA

Publish an existing image

boringcache docker push local-image:tag --as web:$GITHUB_SHA

Push with standard Docker

docker login registry.boringcache.com --username boringcache
docker tag local-image:tag registry.boringcache.com/my-org/my-workspace/web:$GITHUB_SHA
docker push registry.boringcache.com/my-org/my-workspace/web:$GITHUB_SHA

.boringcache.toml

[adapters.docker]
tag = "docker-main"
publish-image = "web:latest"
command = ["docker", "buildx", "build", "."]

Deploy machine

echo "$BORINGCACHE_RESTORE_TOKEN" | docker login registry.boringcache.com --username boringcache --password-stdin
docker pull registry.boringcache.com/my-org/my-workspace/web:latest

Use a workspace-scoped save token to publish and a restore-only token on deployment machines. Standard uploads are resumable and digest-verified; authorized pulls download image layers directly from storage.

Docker adapter guide →

Diagnostics labels

Add short, stable labels when they make sessions easier to group. BoringCache already records the adapter and derives new-versus-recurring misses from cache lifecycle data.

Useful labels: project=web, tool=gradle, lane=ci, or workflow=build.

Keep out: commit SHAs, run ids, timestamps, credentials, source text, and other per-run values.

Override order: repo config is the default, BORINGCACHE_PROXY_METADATA_HINTS can replace it for a wrapper, and explicit --metadata-hint flags win last.

No cold/warm labels: BoringCache derives that state from cache targets and lifecycle telemetry.

Need help or found something unclear? Open an issue or browse the CLI repo.