Skip to content
Documentation

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.

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

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.

Build and publish
boringcache docker --publish-image web:$GITHUB_SHA
Publish an existing image
boringcache docker push local-image:tag --as 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. 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.

Sign with a local key
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.

Verify OCI 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.

Attach an SBOM
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.

Tags and image indexes
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.

CI with a Machine connection
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.

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.