Examples and templates

Who this is for: anyone who wants a working starting point rather than a blank file. What you'll have at the end: the right example for your situation, and a client-side pattern that matches how you want work split between laptops and a fleet. Time: varies; the point of this page is to find the thing, not to read it.

Three kinds of starting point ship in the repo, and they answer different questions.

Server configs

is the largest and most useful collection. Every file is a complete, loadable config.

Start from the file closest to your situation and read its comments; several of them explain constraints you'd otherwise discover the hard way, like why a worker's fast store must be a filesystem store.

How-to guides is the task-oriented version of that table if you already know which backend you want.

Deployment topologies

holds deployment material rather than single config files: the docker-compose/ stack, a RHEL 8 Dockerfile (rhel/), the metrics pipeline configs and dashboards (metrics/), and the persistent-worker rule sketches (persistent-workers/).

The docker-compose/ one is the most useful of them, because it is the topology the project's own integration tests run against: a CAS process on 50051, a scheduler with the execution and AC services on 50052, a worker, and the scheduler's worker API on 50061 left unpublished so it is only reachable inside the compose network.

cd deployment-examples/docker-compose
docker compose up

Local testing covers running this and pointing a build at it; Production configuration covers what changes when it stops being a demo.

Project templates

The flake ships templates for the client side: a project already wired to a Nix-pinned toolchain.

nix flake show github:TraceMachina/nativelink

mkdir my-rbe-test && cd my-rbe-test
nix flake init -t github:TraceMachina/nativelink#bazel
git init && git add -A   # what templates/README.md tells you to do; a flake in a git repo only sees tracked files
nix develop

The template does not bundle a NativeLink server; you point it at one you already have. It is also Linux-only, because the lre-cc toolchain it wires in currently supports x86_64-linux only. Toolchains and hermeticity walks the whole flow with real output, including the user.bazelrc values.

To customise: it's a flake, so fork and edit. The usual changes are pointing user.bazelrc at a real cluster, adding platform properties in platforms/BUILD.bazel, and pinning inputs.nativelink.url in flake.nix to a specific commit, kept in sync with the local-remote-execution override in MODULE.bazel.

Three client-side patterns

Independently of which config you start from, there are three ways teams wire their builds. Most adopt them in this order.

Pattern A: Cache only

Every action runs locally; results land in the shared cache. No worker fleet needed, which makes it the cheapest thing that helps.

bazel build //... \
  --remote_cache=grpc://nativelink.internal:50051 \
  --remote_instance_name=main

Right when you have one CI environment building similar things repeatedly, when you want shared caching across laptops without operating workers, or when you're still evaluating. This is Getting started.

Pattern B: Cache plus execution

Actions ship to a worker fleet; the cache underneath stores everything.

bazel build //... \
  --remote_cache=grpc://nativelink.internal:50051 \
  --remote_executor=grpc://nativelink.internal:50052 \
  --remote_instance_name=main \
  --jobs=200

--jobs=200 is the change people forget. Without it Bazel dispatches only as many actions as your laptop has cores, and the fleet sits idle; the limiting factor is supposed to be pool size, not local CPU count.

Right when full builds take hours, when you're trying to shrink a CI fleet, or when you need actions to run on hardware developers don't have.

Pattern C: Hybrid

Small actions local, everything else remote, decided by policy.

bazel build //... \
  --remote_cache=grpc://nativelink.internal:50051 \
  --remote_executor=grpc://nativelink.internal:50052 \
  --remote_instance_name=main \
  --modify_execution_info=Javac=+no-remote-exec \
  --strategy=Javac=local

This forces Javac local (for very small compilations the round-trip dominates) while everything else goes remote.

Right when your workload mixes very fast and very slow actions, or when latency to the fleet is high enough that small actions lose. Reach for it when you have telemetry showing where time actually goes, not before; Tuning covers getting that telemetry.

Choosing

The speedup numbers you'll see quoted for these vary by an order of magnitude between workloads, and mostly reflect how much of a given build is cache-missing compilation. Measure your own before committing to a shape.

FAQ