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

# Remote Cache & Execution

> Share build results across machines with the REAPI-compatible remote cache, and offload execution to workers with rbs remote.

`rbs remote` turns the shared cache into a team resource. One command starts a
remote cache server speaking the standard Remote Execution API (REAPI) — the same
protocol Bazel uses — backed by the same content-addressed store your local builds
use. Any workspace pointed at it gets cache hits for actions anyone else already
ran.

## What works today

* **Remote cache** — stable. Full REAPI, so rbs workspaces and Bazel clients can
  share one cache server.
* **Remote execution** — available for rbs clients: workers can join the cluster
  and execute cache misses. This surface is newer; treat it as early.

<Note>
  Remote execution and workers are still maturing — the remote cache is the solid
  core. Remote execution currently accepts rbs clients only; REAPI execution for
  foreign clients (e.g. Bazel) is not available yet. Bazel interoperability applies
  to the **cache**.
</Note>

## Start a cache server

```bash theme={null}
rbs remote serve
```

That is the whole setup. The server:

* listens for REAPI clients on port `8980` (change with `--port`),
* stores content in the shared per-user store (change with `--dir`),
* generates a bearer token on first start, persists it, and prints it with
  ready-to-paste client commands.

Pass `--token` to choose the token yourself, or `--insecure` to disable
authentication entirely (only for isolated networks). TLS is configured through
environment variables when you need it: `RBS_REMOTE_TLS_CERT` and
`RBS_REMOTE_TLS_KEY` serve TLS, and `RBS_REMOTE_TLS_CLIENT_CA` additionally
requires client certificates.

By default `rbs remote serve` also starts one colocated worker, so a single
machine is already a complete cluster; `--workers 0` serves the cache only.

## Connect a workspace

Point builds at the cache with `--remote`, authenticating with the token the
server printed:

```bash theme={null}
export RBS_REMOTE_TOKEN=<token>
rbs build //... --remote host:8980
```

Or set the address once and let every build pick it up:

```bash theme={null}
export RBS_REMOTE=host:8980
export RBS_REMOTE_TOKEN=<token>
rbs build //...
```

Cache misses build locally and upload their results; the next machine to need
them downloads instead of rebuilding. If you explicitly request a remote that
cannot be reached, the build fails rather than silently continuing local-only —
you always know whether you got what you asked for.

### Bazel as a client

The cache speaks real REAPI, so a Bazel project can share it:

```bash theme={null}
bazel build //... \
  --remote_cache=grpc://host:8980 \
  --remote_header="authorization=Bearer <token>"
```

## Remote execution

With workers in the cluster, `--remote-exec` offloads cache misses to them
instead of building locally:

```bash theme={null}
rbs build //... --remote host:8980 --remote-exec
```

Add capacity from any machine:

```bash theme={null}
rbs remote worker --server host:8980     # token via $RBS_REMOTE_TOKEN
```

Workers dial out to the server — no inbound connectivity to worker machines is
required. Useful worker flags: `--name`, `--jobs` (concurrent actions, default:
CPU count), `--work-dir`, and `--health-check` (a script run periodically;
non-zero exit drains the worker).

Check on the cluster at any time:

```bash theme={null}
rbs remote status
```

```text theme={null}
🌐 cluster host:8980
   workers:   3
   executing: 5   queued: 12
   jobs:      2 pending, 1 running
```

Two properties worth knowing:

* **A successful remote execution is just a cache hit.** The worker publishes the
  result to the cache and your build restores it through the same validated path
  as any other hit.
* **The cluster can never fail a build your machine could complete.** Any remote
  execution failure falls back to local execution with a warning.

`--remote-download` (`all`, `toplevel`, `minimal`) controls which remote outputs
are downloaded to the workspace; it requires hermetic execution roots
(`RBS_EXECROOT=1`) and is ignored otherwise — with a message saying so.

## Secrets never leave your machine

Variables declared `secret = True` in your `.env.schema` get special treatment
end to end: an action that consumes one is **refused for remote execution** and
runs locally instead, because shipping it would transmit the secret value to the
cache server and workers in cleartext. The build still completes — the secret
action just executes on your machine — and the error/warning names the variables
involved, so you always know why a target stayed local.

This is deliberate, not a gap to work around: if a target should execute
remotely, stop marking its variables secret; if its variables are secret, it
runs locally.

## CI on the cluster

`rbs ci run --remote host:8980` runs a whole CI workflow's jobs on the cluster,
with job dependencies preserved and every job sharing the cluster's cache. See
[CI workflows](/ci/overview#running-ci-on-a-cluster).