Skip to main content
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.
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.

​
Start a cache server

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:
Or set the address once and let every build pick it up:
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:

​
Remote execution

With workers in the cluster, --remote-exec offloads cache misses to them instead of building locally:
Add capacity from any machine:
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:
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.