Concepts

Workspaces

Workspaces isolate Cache, Artifacts, Registry images, and access. Their namespace/workspace address identifies a workspace in a personal account or organization. Cache and Artifacts use the workspace storage connection; Registry uses managed storage.

Create and manage workspaces in the dashboard.

Tags & Platform

Tags identify cache entries inside a workspace. By default, BoringCache adds platform suffixes such as deps-ubuntu-22.04-amd64 so incompatible binaries are not mixed across OS and architecture. Use --no-platform only for portable cache content.

Tags are also git-aware by default. On save, feature branches write to a branch-suffixed tag; on restore, the CLI checks that branch tag first and then falls back to the default-branch tag. Disable this with --no-git or BORINGCACHE_NO_GIT=1.

Content-Addressed Storage

BoringCache identifies stored content by digest so saves can reuse data already in the workspace. The CLI detects supported structured layouts automatically and uses archives for other directories.

The cache allowance is shared across workspaces in your account and measured as compressed bytes at rest. Matching cache content is stored once within a workspace. An optional workspace cleanup budget does not reserve capacity from the shared allowance.

New saves continue while BoringCache reclaims cache in the background using retention and least-recently-used order. Protected targets are reclaimed last when capacity requires it. Cache excess is reclaimed instead of billed as an overage. Artifacts and Registry have separate allowances and are never reclaimed as cache.

Archive saves split a deterministic tar stream into compressed chunks and upload chunks missing from storage. Unchanged chunks can be reused across saves. The archive representation is selected automatically.

Restore verifies downloaded content and reconstructs the directory, preserving modification times needed by build tools. Downloads and extraction can overlap. Archive handling is built into the CLI; no system tar is required.

Security

BoringCache signs published cache entries with an Ed25519 workspace key. Signatures bind the accepted content to that workspace; they do not establish that the build inputs were trustworthy.

The CLI checks content digests during restore. Signature failures warn by default; BoringCache One requires valid server signatures. Use --require-server-signature or BORINGCACHE_REQUIRE_SERVER_SIGNATURE=1 for strict verification elsewhere.

Token permissions decide who can publish. If a low-trust job gets a save or admin token, it can publish cache state that the server will accept and sign.

A pinned publisher policy in .boringcache.toml can require BoringBuild OIDC or GitHub Sigstore evidence for protected Cache, compiler/KV, Artifact, and Registry reads. Cache and compiler/KV verification failures become misses by default; explicit Artifact and Registry pulls fail. A mutable tag can still refer to an older, correctly signed entry.

Configure publisher trust.