Documentation
Getting started
On this page
j / k move between sections.
Docs / Adapter commands
Adapter commands
One command per supported tool: connect its native cache, run the build, and finish publication before the command exits.
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/*
Bazel REAPI
boringcache bazel-reapi
REAPI gRPC action cache and content-addressable store; cache only
Moon
boringcache moon
REAPI gRPC action cache and content-addressable store; cache only
Pants
boringcache pants
REAPI gRPC action cache and content-addressable store; cache only
Buck2
boringcache buck2
REAPI gRPC action cache and content-addressable store; cache only
sbt 2
boringcache sbt
REAPI gRPC action cache and content-addressable store; cache only
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
Adapter configuration
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.
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.
Push images with the BoringCache CLI. It uploads image layers directly to Registry storage. Pushing with docker push, docker buildx build --push or a BuildKit type=registry cache export is not supported. Pull with Docker or any OCI client. When the local Docker engine exports layers uncompressed, the CLI stores them as zstd; pulling those needs Docker Engine 23 or later, containerd 1.5 or later, or a current Podman or CRI-O.
A workspace can contain multiple image repositories. The first push to a repository name creates it automatically; later pushes add or update tags in that repository. In web:latest, web is the repository and latest is its image tag. To clean up an image, open its repository in Registry, select the tag or digest, then remove a tag or delete the digest from image details. When a tag moves to another image, the previous image stays available by digest until you delete it. To delete untagged images automatically, set Delete untagged images after in Registry settings. Registry then deletes an image that many days after no tag points to it, and deletes its layers 24 hours later unless another image uses them.
Registry Settings offers an optional managed storage write cap for the workspace. Confirmed stored layers count toward it; layers shared by images in that workspace count once. Usage updates after upload confirmation, so concurrent uploads can temporarily exceed the cap. A full cap stops new uploads while existing images remain available. BYOC bytes are excluded. Raising a workspace cap does not increase the namespace storage allowance.
Registry stores images. For BuildKit layer cache, use boringcache docker, which keeps the cache in BoringCache Cache with its own retention.
During a trial, new image pushes stop after 30 days. Pulls remain available for seven more days, then remaining managed Registry data is scheduled for deletion unless you subscribe. See the trial policy.
boringcache docker --publish-image web:$GITHUB_SHA
boringcache docker push local-image:tag --as web:$GITHUB_SHA
[adapters.docker] tag = "docker-main" publish-image = "web:latest" command = ["docker", "buildx", "build", "."]
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. Authorized pulls download image layers directly from storage.
Sign images and publish attachments
Publish OCI signatures with boringcache docker sign. Use a local cosign private key, or a local PEM private key and certificate chain for Notation. Install cosign 3 or Notation 1.3.2 on the signing machine. The command resolves the image once and signs its immutable digest; it uploads the signature through BoringCache.
boringcache docker sign web:latest --key ./cosign.key boringcache docker sign web:latest --signer notation --key ./publisher.key --certificate ./publisher.crt
Set COSIGN_PASSWORD for an encrypted cosign key. Notation requires an unencrypted local PEM key. KMS keys are not supported. These signatures have no transparency-log or trusted-timestamp record. Verify them independently with your approved key or certificate trust policy; ordinary Docker pulls do not verify signatures.
cosign verify --key ./cosign.pub --offline --insecure-ignore-tlog registry.boringcache.com/my-org/my-workspace/web@sha256:DIGEST notation verify registry.boringcache.com/my-org/my-workspace/web@sha256:DIGEST
Authenticate each verifier for Registry reads. For Notation, configure your approved certificates with notation cert add and import a trust policy with notation policy import. Set its repository scope, trusted certificate store and signer identities. A stored signature is not proof that your policy accepts it.
boringcache docker attach web:latest --file sbom.json --artifact-type application/vnd.cyclonedx+json --media-type application/vnd.cyclonedx+json
Signatures and attachments are discoverable through OCI referrers. They stay reachable while a tag reaches their subject, including through an image index. Removing the last tag starts the workspace's optional untagged-image retention period. Deleting a subject digest does not immediately delete its attachments; they become untagged content under the same policy. Deleting an attachment digest removes that attachment without deleting its subject.
Retag images and assemble an image index
Add or move a tag without uploading layers. Assemble an index from image manifests already published in the same repository. Specify the platform for each member; the CLI does not infer it. Cross-repository copies and appending to an existing index are not supported.
boringcache docker tag web:build-123 web:stable boringcache docker index --as web:latest --platform linux/amd64=web:amd64 --platform linux/arm64=web:arm64
Pull with standard Docker in CI
Run boringcache docker login once on the machine. It installs docker-credential-boringcache next to the CLI and registers it for registry.boringcache.com in Docker's config.json. Docker and buildx then ask BoringCache for a Registry credential each time they sign in to pull an image. With a Machine connection, each request gets a new credential that lasts five minutes. Without a Machine connection, the helper uses BORINGCACHE_SAVE_TOKEN, or BORINGCACHE_RESTORE_TOKEN when no save token is set.
boringcache docker login boringcache ci run -- docker pull registry.boringcache.com/my-org/my-workspace/web:$GITHUB_SHA
Availability: boringcache docker login requires CLI 1.42.0 or later.
GitHub Actions: after boringcache/one starts a Machine connection, later steps in the same job can run docker and docker buildx directly, without boringcache ci run.
buildx version: use buildx 0.23 or newer. Older versions reuse one credential for ten minutes, and it expires after five.
Long transfers: a classic docker pull that runs longer than five minutes can fail when its credential expires.
Publisher checks: standard Docker pulls do not verify who published an image. boringcache docker pull verifies the publisher first.
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.