Skip to main content
rbs has exactly one build cache: a user-global, content-addressed store shared by every workspace on your machine. Build a target in one workspace, and any other workspace that produces the same action gets a cache hit — no per-project cache directories to warm up or clean out.

​
Where the cache lives

By default the store lives under ~/.cache/rbs (the content store itself sits in a versioned subdirectory, e.g. ~/.cache/rbs/v1). To relocate it — for example onto a larger volume — set RBS_CACHE_DIR:
Your workspace’s .rbs/ directory is not a cache. It holds only materialized state — build outputs, toolchain links, resolved external dependencies — all of which rbs recreates on demand. Deleting .rbs/ forces a rebuild but loses nothing durable.
The cache is user-global. Every workspace on the machine reads from and writes to the same store, so cache management commands affect all of your projects at once — never just the one you happen to be standing in.

​
What gets cached

The store holds two kinds of entries:
  • Content blobs — the files actions produce (and consume), addressed by their content hash. Identical content is stored once, no matter how many targets or workspaces reference it.
  • Action results — a record that a given action (command + inputs + environment) already ran, pointing at the blobs it produced. When you rebuild, rbs looks up each action here and restores its outputs instead of re-executing it.
Alongside the content store, rbs keeps other user-global caches that the rbs cache commands manage with the same age bounds:
  • OCI images — container images pulled for image-based rules
  • Toolchains — downloaded language toolchains (see Toolchains)
  • External deps — resolved third-party packages (see External dependencies)
  • Terraform providers — provider plugins downloaded for infra targets

​
Inspecting the cache

This reports the store location and the size of each cache:
Run inside a workspace, stats also breaks down that workspace’s materialized .rbs/ state, one line per top-level directory — useful for seeing where local disk usage actually is:

​
Bounding the cache: rbs cache gc

Garbage collection is the recommended way to keep the cache in check. It sweeps entries by age first, then evicts the least-recently-used content until the store is under its size budget:
Age values support weeks and days on top of the usual units: 2w, 7d, 24h, 30m, 90s. The same pass also ages out the OCI image cache, the toolchain store, the external-deps store, and Terraform providers. Anything swept is rebuilt or re-downloaded automatically the next time it’s needed.
You rarely need to run gc by hand — rbs runs a bounded GC pass automatically at most once per day after builds. Run it manually when you want space back right now.

​
Removing entries: rbs cache clean

clean removes store entries outright:
Bare rbs cache clean — with no flags — is refused:
Because the store is shared, “clean this project” is never what emptying it would do. Make the intent explicit with --max-age or --all. Everything clean removes is rebuildable — but after --all, every build on the machine starts from scratch.