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

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

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

```text theme={null}
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:

```text theme={null}
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`:

```text theme={null}
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:

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.