Documentation
Getting started
On this page
j / k move between sections.
Docs / Concepts
Concepts
Workspaces, tags and platform suffixes, content-addressed storage, and the security model.
Workspaces
Workspaces group Cache, Artifacts and Registry under shared access. Their namespace/workspace address identifies a workspace in a personal account or organization. Each product has its own storage connection, retention and deletion controls.
Create and manage workspaces in the dashboard.
The trial lasts 30 days. After that, new saves, uploads and pushes stop. Remaining data can be downloaded for seven more days, then managed Cache, Artifacts and Registry data is scheduled for deletion unless you subscribe. This includes permanent Artifacts and published files. Physical cleanup may take longer. Normal unused-cache retention still applies.
Create a workspace, then choose Cache, Artifacts or Registry. Each product's Overview offers its storage setup before the first upload. BoringCache storage with automatic placement is the default; every paid plan and the trial also offer managed regional storage policies. The trial and Custom offer a separate BYOC connection for each product. Storage setup starts when you enable it; the other products remain unconfigured. Overview updates setup status automatically while storage is queued or provisioning, then shows usage instructions when it is ready. Cache Settings includes protected tag patterns under Retention: matching current targets skip unused-cache retention while still counting toward storage usage.
Tool-cache retention is renewed by writes, published working sets, CLI read reports and download links, including prefetch links. The number of versions kept controls prefetch selection; it does not delete tool-cache keys.
You can create workspace tokens before configuring storage. Token access applies across Cache, Artifacts and Registry. Product onboarding shows existing access and links to Tokens; the token pages link back to workspace setup while storage is not ready. A token value is shown only when it is created.
Storage and billing
Cache, Artifacts and Registry share one managed storage pool across all workspaces in a namespace. BYOC bytes do not consume this pool. Product retention and deletion controls remain separate.
Cache, Artifacts and Registry each have a Storage page with their own location settings. Saving a location queues a change. The page shows when that change is pending or has failed; save again to retry a failed change. Regional charges use the applied region confirmed by the storage provider, including while a change to automatic placement is pending. Each product contributes its own stored bytes. BYOC location and replication are controlled and billed by your provider.
On active card-billed Standard and Large, an admin can set an extra-storage budget in Billing. It defaults to $0. Storage above the included pool costs $0.04/GB-month, measured daily and capped at the budget in each subscription billing period. The budget carries forward each month and does not cover regional charges.
Each $1 of budget adds 25 GB to the storage limit; a $20 budget adds 500 GB. Confirmed stored bytes count toward usage, and reused objects count once. Usage updates after upload confirmation; uploads already in progress can finish and temporarily exceed the limit. New uploads stop once measured usage reaches the limit. BYOC does not consume this pool. Lowering the budget keeps your data, but new managed uploads wait if usage is at or above the new limit. A budget cannot be lower than the extra-storage charge already recorded that period. The trial keeps its fixed allowance; Custom storage follows its contract.
Automatic placement and one pinned region are included. Multi-region geography is $0.03/GB/month. For specific regions, the first is included and each additional region is $0.03/GB/month. On Standard and Large, regional storage is measured daily and billed monthly, separately from any extra-storage budget. The no-card trial has no usage charges; Custom follows its contract.
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 storage allowance is shared by all products and workspaces in your namespace. Cache usage is measured as compressed bytes at rest. Matching cache content is stored once within a Cache storage connection.
New uploads stop when confirmed usage reaches the storage limit, including any extra-storage budget. Usage updates asynchronously, so uploads already in progress can finish and temporarily exceed the limit. Saves can still reuse stored content. When a new upload is rejected, the CLI reports an optional cache save as skipped, the previous version stays current, and the build keeps its exit status. CLI releases without storage-allowance handling retry the rejected request and then report a failed save. Existing caches stay available and are removed only after going unused for their retention period; BoringCache does not delete cache to make room. Each product handles its own cleanup.
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.
| Layout | Storage |
|---|---|
| OCI image layout | Detected by index.json + oci-layout + blobs/sha256/. Each blob stored by SHA-256 digest. |
| Bazel disk cache | Detected by ac/ + cas/ directories. Each file stored by digest. |
| Everything else | Archive transport with reusable compressed chunks. |
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.
Need help or found something unclear? Open an issue or browse the CLI repo.