> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Caching

> How the shared content-addressed cache speeds up builds, and how to inspect and manage it with rbs cache.

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`:

```bash theme={null}
export RBS_CACHE_DIR=/mnt/bigdisk/rbs-cache
```

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.

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

## 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](/build/toolchains))
* **External deps** — resolved third-party packages (see
  [External dependencies](/build/external-dependencies))
* **Terraform providers** — provider plugins downloaded for infra targets

## Inspecting the cache

```bash theme={null}
rbs cache stats
```

This reports the store location and the size of each cache:

```text theme={null}
📊 Cache Statistics
===================
Store: /Users/you/.cache/rbs/v1
   (shared across every workspace for this user)

📦 Content blobs: 12841 (3120.44 MB)
🎯 Action results: 1904 (12.10 MB)
🐳 OCI images: 812.30 MB
🔧 Toolchains: 1450.02 MB
📚 External deps: 640.88 MB
🧩 Terraform providers: 210.55 MB

📊 Total: 6246.29 MB
```

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:

```text theme={null}
🗂  Workspace state: /Users/you/myproject/.rbs
   gocache            2140.11 MB
   out                 890.45 MB
   toolchains            0.02 MB
   total              3030.58 MB
   (materialized from the store and sources; deleting it forces a rebuild but loses nothing durable)
```

## 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:

```bash theme={null}
# Defaults: drop anything not accessed in 30 days, keep the store under 20 GiB
rbs cache gc

# Custom bounds
rbs cache gc --max-age 14d --max-gb 10
```

| Flag        | Default | Meaning                                                               |
| ----------- | ------- | --------------------------------------------------------------------- |
| `--max-age` | `30d`   | Collect anything not accessed within this window                      |
| `--max-gb`  | `20`    | Size budget in GiB; least-recently-used blobs beyond it are collected |

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.

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

## Removing entries: `rbs cache clean`

`clean` removes store entries outright:

```bash theme={null}
# Remove entries older than 7 days
rbs cache clean --max-age 7d

# Remove everything (every workspace's next build goes cold)
rbs cache clean --all
```

Bare `rbs cache clean` — with no flags — is **refused**:

```text theme={null}
refusing to empty the shared store at /Users/you/.cache/rbs/v1 — it is used by every workspace for this user
  rbs cache gc                bound it by age and size (recommended)
  rbs cache clean --max-age 7d  remove entries older than 7 days
  rbs cache clean --all         remove everything (rebuildable, but every build goes cold)
```

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.