# Bazel cache

Reuse Bazel build artifacts across runs. The cache is shared between your CI workflows and local builds.

Namespace provides high-performance [Bazel](https://bazel.build) caching with very low network latency between runners and the cache storage. This allows your Bazel workflows to reuse build artifacts across runs, irrespective of your chosen granularity, significantly reducing build times.

Bazel caching is particularly effective for:

* Build steps that are time-consuming to execute
* Projects where compilation is typically slow, such as Rust and C++ codebases
* Workflows that can benefit from cross-invocation artifact reuse

Since the cache is shared, local builds can also benefit from artifacts already cached by CI, and vice versa.

## Getting started

Bazel caching is a paid add-on. In order to enable it for your workspace contact [our sales team](mailto:sales@namespace.so).
You can produce a ready-to-use configuration with [`nsc bazel setup`](/content/docs/reference/cli/bazel-setup/index.html):

### 1. Configure cache access

```bash theme={null}
nsc bazel setup --remote=false --bazelrc /etc/bazel.bazelrc
```

This command generates short-term credentials and sets up a `bazelrc` configuration file.

### 2. Use the Bazel cache

```bash theme={null}
bazel --bazelrc=/etc/bazel.bazelrc test //..
```

You can pass multiple configuration files by setting `--bazelrc` repeatedly, allowing you to combine your existing configuration with Namespace cache access. See [Bazel's documentation](https://bazel.build/run/bazelrc) for granularity control options.

### GitHub Actions Example

When using Namespace runners, you can enable Bazel caching directly in your [profile configuration](https://cloud.namespace.so/workspace/actions/profiles).

In your workflow, you only need to select the corresponding profile. Bazel is already configured to use the Namespace cache.

```yaml {3} theme={null}
jobs:
  build:
    runs-on: namespace-profile-with-bazel
  steps:
    - name: Bazel test
      run: bazel test //..
```

## How it works

The Bazel caching solution employs a tiered caching approach, where the hot cache lives as close to the consumer (e.g. your CI job runner) as possible.
The cold caching tier is backed by our [high-performance artifact storage](/content/docs/architecture/storage/artifact-storage.md) and enables Bazel to retain a vast amount of cached artifacts.

Access to the Bazel cache is granted through short-lived secure credentials.

## Usage

Namespace accounts Bazel cache usage in two categories:

* Bazel cache storage
* Bazel cache reads

For detailed billing information for each item as well as included amounts in your plans, visit [the pricing page](/content/pricing/index.html).

## Remote Asset API

Namespace implements Bazel's [Remote Asset API](https://github.com/bazelbuild/remote-apis/blob/main/build/bazel/remote/asset/v1/remote_asset.proto), which lets Bazel offload external downloads to the Namespace cache instead of fetching them directly from the origin.

Namespace's remote Bazel caches support:

* **Checksum-verified fetches** using the `checksum.sri` qualifier (SHA-256).  When Bazel provides an integrity hash, Namespace resolves the asset straight from cache without contacting the origin.
* **Custom HTTP headers** via the `http_header:` and `http_header_url:` qualifiers, so authenticated or header-gated downloads work through the cache.
* **HTTP and HTTPS URIs.**

### Enabling

The remote Asset API is opt-in. When using Namespace runners, enable it in your [profile configuration](https://cloud.namespace.so/workspace/actions/profiles) alongside Bazel caching. The generated `.bazelrc` will contain the necessary flags automatically, so you only need to select the profile:

```yaml {3} theme={null}
jobs:
  build:
    runs-on: namespace-profile-with-bazel
  steps:
    - name: Bazel test
      run: bazel test //..
```

When configuring the cache with the [CLI](/content/docs/reference/cli/installation.md), pass the `--enable_remote_asset_api` flag to include the remote asset endpoint in the generated bazelrc:

```bash theme={null}
nsc bazel setup --remote=false --enable_remote_asset_api --bazelrc /etc/bazel.bazelrc
```

## Running Bazel from a Devbox

You can create a [Devbox](/content/docs/devbox.md) with Bazel caching already configured. Namespace runs the setup for you, so `bazel` uses the Namespace cache without any further steps.

### 1. Enable Bazel caching

Turn on caching when you create the Devbox, and select the repository holding your Bazel project at the same time. The Devbox then starts with the repository cloned and the cache configured, ready to build.

**Create wizard**

Create a new Devbox from the [Devboxes](https://cloud.namespace.so/workspace/devboxes) page and select your repository. Expand the **Advanced** section and turn on **Bazel cache**.

**Blueprint**

Use a [Blueprint](/content/docs/devbox/blueprint.md) so every Devbox created from it has caching configured. Set the repository in the **Repository** dropdown, then find the **Integrations** section and turn on **Bazel**.

To add caching to a Devbox that was created without it, open a shell in the Devbox and run setup against the same path the toggle configures:

```bash theme={null}
nsc bazel setup --bazelrc=/home/devbox/.bazelrc --remote=false
```

### 2. Run Bazel from the Devbox

Open a shell in the Devbox:

**Devbox CLI**

```bash theme={null}
devbox ssh my-devbox
```

**Dashboard**

Open the terminal on your Devbox from the [Devboxes](https://cloud.namespace.so/workspace/devboxes) page.

Then build as you normally would:

```bash theme={null}
bazel build //...
```

You do not need a `--bazelrc` flag. Namespace writes the configuration to `/home/devbox/.bazelrc`, which is the `devbox` user's home `bazelrc`, so Bazel picks it up automatically.

The Devbox also sets a `BAZELRC` environment variable pointing at that file. Use it when you need to name the configuration explicitly, for example from a script or a Makefile that combines it with your own configuration:

```bash theme={null}
bazel --bazelrc=$BAZELRC --bazelrc=tools/bazelrc/rbe.bazelrc build //...
```

The same applies to commands run with [`devbox exec`](/content/docs/devbox/exec/index.html), which is the usual way to drive builds from CI or from a coding agent:

```bash theme={null}
devbox exec my-devbox -- bazel build //...
```

To also run the Bazel actions on Namespace compute, see [Remote Execution from a Devbox](/content/docs/bazel/execution.md#remote-execution-from-a-devbox/index.html).

## Bazel cache from GitHub-hosted runners

You can use the Namespace Bazel cache from GitHub-hosted runners. This lets you validate your cache setup before migrating your runners to Namespace.

> [!NOTE]
> Performance in this setup is not representative of running your full workflow on Namespace.
> From GitHub-hosted runners, cache reads and writes travel over the public internet, adding latency you won't see once your runners run on Namespace.

Use [Identity Federation](/content/docs/federation/github-actions.md#from-github-runners/index.html) to grant GitHub Actions access to the Namespace Bazel cache and other resources.

**Example**
A minimal workflow that configures cache access looks like this:

```yaml theme={null}
name: Example workflow
permissions:
  id-token: write # This is required for federation using OpenID Connect
  contents: read # This is required for actions/checkout
jobs:
  test:
    name: Bazel test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure access to Namespace
        uses: namespacelabs/nscloud-setup@v0
      - run: |
          nsc bazel setup --remote=false --bazelrc /etc/bazel.bazelrc
```

For a full step-by-step walkthrough, see [From GitHub Runners](/content/docs/federation/github-actions.md#from-github-runners/index.html) in the Federation documentation.

## Observability

Namespace records the invocations that run through the cache. Inspect them from the [Bazel invocations](https://cloud.namespace.so/workspace/bazel/invocations) page or with `nsc bazel invocation list`. See [Bazel observability](/content/docs/bazel/observability.md).

## Bazel Remote Execution

Beyond caching, Namespace can run your Bazel actions on Namespace compute, scaling builds horizontally with high parallelism. Remote Execution uses this cache, so remotely executed actions share artifacts with your CI and local builds.

[Learn more about Bazel Remote Execution →](/content/docs/bazel/execution.md)