Introduction
NativeLink is a remote build cache and execution service in one Rust binary. This is the documentation for running it yourself.
NativeLink is a remote build cache and a remote execution service in one program. Your build tool asks it "have you already built this?" and, when the answer is no, "can you build it for me over there?" Your source code doesn't change and your build files don't change: you point your build tool at a URL, and work that used to happen on your machine stops happening on your machine.
It's written in Rust and ships as a single binary that plays every role in the system: cache, scheduler, and worker are the same executable started with different configuration. It speaks the Remote Execution API, an open protocol rather than a NativeLink invention, which is why Bazel, Buck2, Siso, Pants and BuildStream connect to it without a plugin, and why plain CMake projects can via recc.
This site documents the open-source distribution: setting it up, configuring it, deploying it, operating it when other people depend on it, and contributing to it.
Working with agents
If you're pointing a coding agent at NativeLink, at these docs or at the codebase, For agents has the three entry points and what each guarantees. If you're here because your agents are the ones waiting on builds, start with AI coding agents.
The reading path
The first four sections are ordered, and each one assumes the last. You can skip ahead, but the pages will tell you what they expected you to have.
| Section | What you have at the end |
|---|---|
| Getting started | A cache your build is talking to, and hits you can point at |
| Remote execution | Cache misses executing on the farm instead of on your laptop |
| Configuration | The ability to write a config from an empty file instead of copying one |
| How-to guides | The storage backend, transport and upgrade path you actually want, instead of the ones an example gave you |
Two sections are ordered against the reading path without being part of it. Why NativeLink comes before Getting started: what a remote cache and remote execution actually do, and a short check for whether your build is one that benefits. It's worth ten minutes if you haven't decided yet. Operate comes after How-to guides, for when other people depend on your cluster and "it works on my machine" stops being the bar.
Everything else sits outside the ordering: reference material you look things up in, explanations you read when you want to know why, and the contribution guides. Those are entered from a search or a link, at any point.
Start where you are
I'm deciding whether this is for us
- Why NativeLink: the mental model, and the 30-second test for whether your build benefits.
- AI coding agents: why an agent's build loop makes cache hit rate a token-cost question.
- Silicon and large builds: EDA flows, large C++ and LLVM trees, ML graphs.
- Autonomous operation: what it takes to run a farm nobody watches.
- Open source and Enterprise: what's licensed how, and what the paid tiers are actually for.
I want to get something running
- Quickstart: a local cache in under ten minutes.
- Connect your build tool: Buck2, Siso, Chromium, Pants, BuildStream, CMake.
- Shared cache: the single-server deployment that survives a team-wide rollout.
- Your first remote action: once caching works and you want the misses to move too.
I want to configure it
- The config model: how a NativeLink config is put together, in one page.
- Stores: declaring, naming and composing the storage a cache is built from.
- Scheduler and workers: how work gets matched to machines.
- Your first full config: the capstone: a complete cluster written from an empty file.
- How-to guides: TLS and auth, multiple workers, cloud object stores, upgrades, migrating an existing cache.
I want to run it in production
- Production configuration: the three-process split a real cluster runs in.
- Deploy with Docker Compose or on bare metal: the two shapes, and where state lives in each.
- Observability: the OTLP to collector to Prometheus to Grafana pipeline, and the one detail that silently breaks every dashboard.
- Security hardening: what's unauthenticated by default, and what to do about it.
- Runbooks and Troubleshooting: the procedures that end an incident, and the symptom index that tells you which one you're in.
I want to understand how it works
- Architecture: scheduler, CAS, action cache, workers, and what each is responsible for.
- Architecture deep dive: the same system at the level of crates, startup order, and where an action's path forks.
- The store model, scheduler internals and worker execution: one page per subsystem, written against the source.
- Correctness and hermeticity: what a cache hit guarantees, what it doesn't, and which gaps are yours to close.
- Local Remote Execution: making your toolchain and your workers' toolchain the same toolchain, so both share one cache.
- History: why NativeLink exists and what it learned from what came before.
I need to look something up
- Configuration reference: every field, generated from the source.
- Protocol and API surface: every gRPC service,
which RPCs are implemented, and what
Capabilitiesadvertises. - Metrics: every instrument, its type, and whether it's actually emitted.
- CLI and environment: the complete flag and variable surface.
- Glossary and Changelog.
I want to contribute
- Contribution guidelines: what gets accepted and how review works.
- Build from source with Bazel, Cargo, or Nix.
- Writing docs: the archetypes and conventions this site is built on.
FAQ
Every page here ends with an FAQ for its own topic. These are the questions we get most overall.