Bazel cache

Every linux-build box has Bazel and a remote cache on localhost, sealed under your project’s key and shared by the project’s boxes.

linux-build comes with Bazel 8 and a remote cache on localhost:9092, already configured. A box that builds what an earlier box of the same project built gets those steps from the cache.

Use it

Nothing to set up: run Bazel in /work.

envctl env create linux-build --share src=. --project github.com/acme/app
envctl exec linux-build-3f2a -- sh -c 'cd /work && bazel build //...'

INFO: Elapsed time: 45.960s, Critical Path: 11.20s
INFO: 4 processes: 1 internal, 3 local.

Delete the box and lease a fresh one for the same project. The same build now comes from the cache:

INFO: Elapsed time: 34.665s, Critical Path: 0.52s
INFO: 4 processes: 3 remote cache hit, 1 internal.

Most of what’s left is Bazel itself starting in a new box.

How it’s set up

The image’s /etc/bazel.bazelrc:

startup --output_user_root=/cache/bazel
startup --host_jvm_args=-Xmx384m
common --repository_cache=/cache/bazel-repo
build --spawn_strategy=local
build --incompatible_strict_action_env
build --remote_cache=http://127.0.0.1:9092

• Bazel’s state lives on the writable /cache volume; the rest of the box is read-only.
• Actions run as plain processes; under gVisor there’s no room for Bazel’s own sandbox.
• --incompatible_strict_action_env gives actions a fixed PATH, so their cache keys are the same in every box.

Where the cache lives

• envd in the box serves Bazel’s HTTP cache protocol on localhost:9092. Before a record leaves the box, envd seals it under your project’s key with a fresh nonce and names it with a keyed hash of its digest. Content-addressed records are checked against their digest on the way in and on the way out.
• Records are kept on the node, in a folder for your project, behind a token envlet gives each box. One project’s boxes never see another’s records, and the node holds only ciphertext under names that reveal nothing.
• When you lease a project’s next build box, the API starts it on the node that holds the cache, if that node has room. The least recently used records go first when the node’s cache is full.

Use it from your machine

Each linux-build box exports the cache, so your sandbox has it on 127.0.0.1:9092 too:

bazel build //... --remote_cache=http://127.0.0.1:9092 --incompatible_strict_action_env

Cache keys include the platform, so a Mac’s actions hit what Macs stored and Linux boxes hit what Linux boxes stored. Platform-independent actions, like code generation, are shared by both.

Limits

• Records up to 64 MiB are cached; Bazel builds bigger outputs without the cache and carries on.
• The cache is per node, not in object storage. A box that can’t go to its project’s node starts cold.
• Bazel’s remote execution API isn’t supported. Run Bazel in the box with envctl exec instead.