# NativeLink

> A remote build cache and remote execution service in one Rust binary, for
> build systems that speak the Remote Execution API: Bazel, Buck2, Siso,
> Pants, BuildStream, and CMake via recc. The cache, the scheduler and the
> worker are the same executable started with different configuration.

These docs are ordered as a path, not a catalogue: get a cache serving hits,
then put workers behind the misses, then own the config file, then reach for
the how-to guides. Each section assumes the previous one is working, and every
page on the path opens by stating what it assumes. An agent reading this file
in order learns the same sequence a human learns from the sidebar.

Getting started, then Remote execution, then Configuration, then How-to guides.
Why NativeLink comes before that path, and Operate comes after it. Concepts,
Reference and Contribute are outside the ordering: enter them from a search or
a link at any point.

This file is generated from the navigation (`meta.json`) and page frontmatter
by `web/apps/docs/scripts/gen-llms.mjs`, so it cannot drift from the sidebar.

The full corpus with page bodies is at /llms-full.txt.

- [Introduction](https://docs.nativelink.com/): NativeLink is a remote build cache and execution service in one Rust binary. This is the documentation for running it yourself.

## Why NativeLink

- [Why NativeLink](https://docs.nativelink.com/use-cases): What NativeLink is, what a remote cache and remote execution actually do, and a 30-second check for whether your build is one that benefits.
- [AI coding agents](https://docs.nativelink.com/use-cases/ai-coding-agents): An agent's edit-build-test loop runs far more often than a human's, so build time sets both its wall clock and a large part of its token bill, and a shared cache turns most of those iterations into downloads.
- [Autonomous operation](https://docs.nativelink.com/use-cases/autonomous-operation): What it takes for a build farm to grow and shrink with demand without anyone watching it: which properties NativeLink gives you, which pieces you assemble yourself, and where the seams are.
- [Silicon and large builds](https://docs.nativelink.com/use-cases/silicon-and-large-builds): EDA flows, large C++ and LLVM trees, and ML graphs are the workloads remote execution was invented for: thousands of actions, hardware that differs from action to action, and a long tail that decides the wall clock.

## Getting started

- [Getting started](https://docs.nativelink.com/getting-started): The first section of the reading path: a cache running, connected to your build, proven to be hitting.
- [Quickstart](https://docs.nativelink.com/getting-started/quickstart): Install NativeLink and point your build system at it in under 10 minutes.
- [Verify your cache](https://docs.nativelink.com/getting-started/verify-your-cache): Prove the cache is actually serving hits rather than quietly falling back to local work, using your build tool's own accounting, not a status page.
- [Connect your build tool](https://docs.nativelink.com/getting-started/connect-your-build): Use NativeLink without Bazel: Buck2, Siso, Pants, BuildStream, and CMake with recc.
- [Buck2](https://docs.nativelink.com/getting-started/connect-your-build/buck2): Configure Buck2 to use NativeLink for remote cache and execution.
- [Siso](https://docs.nativelink.com/getting-started/connect-your-build/siso): Point Siso at NativeLink for Chromium-style remote caching and execution.
- [Chromium](https://docs.nativelink.com/getting-started/connect-your-build/chromium): Building Chromium with NativeLink as the Siso backend, a worked example for the largest public consumer.
- [Pants](https://docs.nativelink.com/getting-started/connect-your-build/pants): Enable Pants remote caching with NativeLink.
- [BuildStream](https://docs.nativelink.com/getting-started/connect-your-build/buildstream): Configure BuildStream to use NativeLink for artifact storage and remote execution.
- [CMake with recc](https://docs.nativelink.com/getting-started/connect-your-build/cmake-recc): Accelerate CMake builds with NativeLink as a remote cache, using recc as the bridge.
- [Shared cache](https://docs.nativelink.com/getting-started/shared-cache): Self-host NativeLink on hardware you control, with the operational checklist a team rollout actually needs.

## Remote execution

- [Remote execution](https://docs.nativelink.com/remote-execution): Workers that run the actions your cache misses.
- [From cache to execution](https://docs.nativelink.com/remote-execution/from-cache-to-execution): You have a cache serving hits. This is what changes when the misses stop running on your laptop: in the deployment, in the build invocation, and in what breaks first.
- [Your first remote action](https://docs.nativelink.com/remote-execution/first-remote-action): Run a scheduler and a worker on your own machine, point Bazel at them, and watch a build action execute somewhere other than where you typed the command.
- [Platform properties](https://docs.nativelink.com/remote-execution/platform-properties): How the scheduler decides which worker gets an action, why a mismatch queues forever instead of failing, and how to read the matching diagnostics it already emits.
- [Toolchains and hermeticity](https://docs.nativelink.com/remote-execution/toolchains-and-hermeticity): Your action ran on a worker and failed on a missing compiler. Here is why that happens, and how to pin the toolchain so local and remote builds hash identically.
- [Containers and images](https://docs.nativelink.com/remote-execution/containers-and-images): What the container-image property actually does (and doesn't), plus how to build worker images and keep what your build requests in sync with what your fleet advertises.
- [Persistent workers](https://docs.nativelink.com/remote-execution/persistent-workers): Keep a JVM or Node compiler process warm across actions instead of paying its startup cost every time, and understand exactly what NativeLink gives up to do it.
- [Local testing](https://docs.nativelink.com/remote-execution/local-testing): Keep a NativeLink cluster on your own machine to test config changes, reproduce scheduler behaviour, and prove a client works, in the two shapes the repo itself uses.
- [Examples and templates](https://docs.nativelink.com/remote-execution/examples-and-templates): Runnable configs, deployment topologies, and project scaffolds you can copy, plus the three client-side patterns most teams actually adopt.

## Configuration

- [Configuration](https://docs.nativelink.com/configuration): The config model on one page, so you can read and write a NativeLink config instead of copying one.
- [The config file](https://docs.nativelink.com/configuration/config-file): JSON5 mechanics, environment substitution, how the binary is pointed at a config, and how to find out a config is wrong before it takes a cluster down with it.
- [Stores](https://docs.nativelink.com/configuration/stores): Declaring stores, naming them, and the idea that unlocks the rest of the config: stores compose, and one store refers to another by name.
- [Servers and services](https://docs.nativelink.com/configuration/servers-and-services): Listeners, the eleven services, instance names, and the port split that keeps the worker API off your public interface.
- [Schedulers and workers](https://docs.nativelink.com/configuration/scheduler-and-workers): The minimum config for each, the properties contract between them, and the fields that decide what happens when something goes wrong.
- [Your first full config](https://docs.nativelink.com/configuration/your-first-full-config): An empty file to a running cache-and-execution cluster, one block at a time, checking after each.

## How-to guides

- [How-to guides](https://docs.nativelink.com/how-to): Pick the task you're doing, not the artifact you're reading about.
- [Storage backends](https://docs.nativelink.com/how-to/stores): Every place NativeLink can put bytes, compared on durability, latency and cost, and the composition almost every real deployment lands on.
- [Filesystem store](https://docs.nativelink.com/how-to/stores/filesystem): Put the cache on local disk: the two paths that must share a block device, the eviction policy you cannot skip, and the tuning knobs that matter on real hardware.
- [S3 and compatible](https://docs.nativelink.com/how-to/stores/s3-and-compatible): Back the cache with Amazon S3, Cloudflare R2 or NetApp ONTAP S3: one store type, three providers, and the shared options that decide cost and failure behaviour.
- [Google Cloud Storage](https://docs.nativelink.com/how-to/stores/gcs): Back the cache with a GCS bucket: authentication, the resumable-upload chunk size, and the timeout fields whose names disagree with their units.
- [Azure Blob Storage](https://docs.nativelink.com/how-to/stores/azure): Back the cache with an Azure Blob container: account and container naming, the endpoint override for Azurite, and when a SAS URL replaces everything else.
- [Redis](https://docs.nativelink.com/how-to/stores/redis): Back the cache with Redis (standalone, sentinel or cluster) and the concurrency, chunking and timeout settings that keep it from timing out under a real build.
- [MongoDB](https://docs.nativelink.com/how-to/stores/mongo): Back the cache with MongoDB: collections, write concern, timeouts, and what the change-streams flag is for.
- [Oracle Cloud (OCI) Object Storage](https://docs.nativelink.com/how-to/stores/oci-object-storage): Back the cache with OCI Object Storage through its S3 Compatibility API: Customer Secret Keys, the two adjustments the store makes for you, and what has actually been verified.
- [Compose stores](https://docs.nativelink.com/how-to/stores/compose-stores): The wrapper vocabulary (fast_slow, verify, dedup, existence_cache, size_partitioning, shard and the rest) and the order the layers have to go in.
- [Remote cache compression](https://docs.nativelink.com/how-to/stores/compression): Cut remote cache transfer bytes for compressible artifacts with REAPI zstd wire compression and Bazel's --remote_cache_compression.
- [Content-defined chunking](https://docs.nativelink.com/how-to/stores/chunking-and-dedup): Cut remote cache transfer bytes by 80-90% for incrementally changing artifacts with the REAPI SplitBlob/SpliceBlob extension and Bazel's --experimental_remote_cache_chunking.
- [Run multiple workers](https://docs.nativelink.com/how-to/run-multiple-workers): Add workers to a running NativeLink: how they share the CAS, how the scheduler matches them, and the two things about the shipped compose example that will mislead you.
- [TLS and authentication](https://docs.nativelink.com/how-to/tls-and-auth): Put TLS on the listeners clients reach, use mutual TLS as the access control, and understand exactly what NativeLink does and does not authenticate.
- [Upgrade to a newer version](https://docs.nativelink.com/how-to/upgrade-versions): Read the changelog for the things that actually break, upgrade the three process types in the right order, and know what happens to the cache you already have.
- [Migrate from another REAPI cache](https://docs.nativelink.com/how-to/migrate-an-existing-cache): Put NativeLink in front of your existing cache as a read-only diode, let real builds warm it, and cut over when the hit rate says you can.

## Operate

- [Operate](https://docs.nativelink.com/operate): What to watch, what to tune, and what to do at 3am, once other people depend on your cluster.
- [Production configuration](https://docs.nativelink.com/operate/production-config): The shape a real NativeLink cluster runs in: three processes, a split port surface, and what to turn on before other people depend on it.
- [Tuning](https://docs.nativelink.com/operate/tuning): The lever table: the signal you observe, the knob that moves it, the direction to turn it, and what turning it costs.
- [Deploy with Docker Compose](https://docs.nativelink.com/operate/deploy-docker-compose): Bring up a complete CAS, scheduler and worker on one host with the compose files in the repository: what each service is, which ports it publishes, and the four things that make this a development setup rather than a production one.
- [Deploy on bare metal](https://docs.nativelink.com/operate/deploy-bare-metal): Run NativeLink as systemd services on hosts you own: writing the units, sizing the machines, placing the disks, and rolling an upgrade without dropping in-flight actions.
- [Observability](https://docs.nativelink.com/operate/observability): NativeLink pushes OTLP and nothing else. Wire it to a collector, get the series into Prometheus under the names the shipped rules expect, and know which environment variables actually do something.
- [Security hardening](https://docs.nativelink.com/operate/security-hardening): Open-source NativeLink has no inbound authentication on any service. What that means for your network, which ports must never be routable, how to configure mTLS, and why the worker sandbox is not a security boundary.
- [Scaling workers](https://docs.nativelink.com/operate/scaling-workers): How much work one worker should take, how many workers you need, which signal tells you, and how to let something else make the decision, including the parts NativeLink does not enforce for you.
- [Scaling the CAS](https://docs.nativelink.com/operate/scaling-cas): How to grow the content-addressable store: composing tiers, sizing eviction, sharding, and the specific reasons a second CAS replica is harder than a second worker.
- [An autoscaling reference deployment](https://docs.nativelink.com/operate/autoscaling-reference): The complete Kubernetes deployment that scales workers on queue depth without a human in the loop: every manifest, the reaction-time budget nobody publishes, and the five gaps in the shipped examples you have to close first.
- [Runbooks](https://docs.nativelink.com/operate/runbooks): What to do when a NativeLink deployment is on fire: Redis failover, a worker OOM-killed, the disk full, and the queue backpressured. Each entry is a symptom, the signal that confirms it, the immediate action, and the change that stops it recurring.
- [Troubleshooting](https://docs.nativelink.com/operate/troubleshooting): A symptom-to-cause-to-fix index for NativeLink, anchored on the error strings the system actually emits, including the ones that say nothing useful, and the failures that produce no error at all.

## Concepts

- [Architecture](https://docs.nativelink.com/explanations/architecture): The four roles, who actually writes to the action cache, and which parts of the system hold state you can lose.
- [Architecture deep dive](https://docs.nativelink.com/explanations/architecture-deep-dive): The crate graph, the startup sequence, and the path an action actually takes through the binary.
- [The store model](https://docs.nativelink.com/explanations/store-model): What a store actually is, how composition behaves, and where a digest stops being a claim and becomes a fact.
- [Scheduler internals](https://docs.nativelink.com/explanations/scheduler-internals): Action merging, the awaited-action database, how a worker is chosen, and what happens when an action fails.
- [Worker execution](https://docs.nativelink.com/explanations/worker-execution): How an action becomes a running process: input materialization, what isolation you actually get, and what the worker throws away.
- [Correctness and hermeticity](https://docs.nativelink.com/explanations/correctness-hermeticity): What content addressing guarantees, what it doesn't, and which of the gaps are yours to close.
- [Local Remote Execution](https://docs.nativelink.com/explanations/lre): What LRE actually is: a way to make your local toolchain and your remote workers the same toolchain, so both sides share one cache.
- [History and licensing](https://docs.nativelink.com/explanations/history): What NativeLink was built to replace, the three properties that drove the rewrite, and exactly how the source is licensed.

## Reference

- [Configuration reference](https://docs.nativelink.com/reference/nativelink-config): Every knob in the NativeLink JSON5 configuration — types, defaults, and links to source, autogenerated from the Rust config crate.
- [Store overview](https://docs.nativelink.com/reference/nativelink-config/store-overview): The mental model behind every store in the configuration reference: what holds data, what wraps another store, and how they compose.
- [Protocol and API surface](https://docs.nativelink.com/reference/protocol-api): Every gRPC service NativeLink serves, which RPCs are implemented, and the values it advertises.
- [Metrics reference](https://docs.nativelink.com/reference/metrics): Every OpenTelemetry instrument NativeLink declares, with its type, unit, attributes, Prometheus series, and whether the binary actually emits it. Autogenerated from the Rust source and its call sites.
- [CLI and environment](https://docs.nativelink.com/reference/cli-and-env): Every command-line argument the nativelink binary accepts and every environment variable it reads: the telemetry variables, the ones the configuration expands, and the ones it passes through to actions.
- [Open source and Enterprise](https://docs.nativelink.com/reference/oss-and-enterprise): What the open-source distribution actually contains, which two modules are licensed differently, why nothing in the binary enforces that, and what the paid tiers are for.
- [Glossary](https://docs.nativelink.com/reference/glossary): The vocabulary you need to read the rest of the docs.
- [Changelog](https://docs.nativelink.com/reference/changelog): Notable changes per release. Latest first.

## Contribute

- [Contribution guidelines](https://docs.nativelink.com/contribute/guidelines): What NativeLink accepts, the git setup it requires, and the commit and review conventions a PR is held to.
- [Develop with Bazel](https://docs.nativelink.com/contribute/bazel): Build, test, and run NativeLink with Bazel, the same dev loop CI uses.
- [Developing with Cargo](https://docs.nativelink.com/contribute/cargo): Pure Cargo workflow for NativeLink contributors who'd rather not run Bazel.
- [Develop with Nix](https://docs.nativelink.com/contribute/nix): The dev shell that generates the bazelrc files the rest of the build assumes, and what is actually inside it.
- [Repository and crate map](https://docs.nativelink.com/contribute/repo-crate-map): What every crate and top-level directory in the NativeLink repository is for, and which one your change belongs in.
- [Codebase internals](https://docs.nativelink.com/contribute/codebase-internals): The traits, the error model, the async rules and the two metric systems: the conventions a reviewer will assume you already know.
- [How to extend NativeLink](https://docs.nativelink.com/contribute/how-to-extend): Complete file-by-file recipes for adding a store, a config field, a metric, or a gRPC service.
- [Testing guide](https://docs.nativelink.com/contribute/testing-guide): How NativeLink's tests are organised, what `#[nativelink_test]` gives you, and which local environment problems cause which confusing failure.
- [Releases and versioning](https://docs.nativelink.com/contribute/release-versioning): How a NativeLink version becomes a signed tag, what the tag triggers, and what compatibility the project does and does not promise.
- [Working on documentation](https://docs.nativelink.com/contribute/docs): How these docs are built: the four page archetypes, the components, the anchor and snippet lints, and what a docs PR is reviewed against.

- [For agents](https://docs.nativelink.com/): How an AI agent should read these docs end to end, where every entry point is, how to cite and verify a claim, and what the docs guarantee to a machine reader.

## For agents

- [AGENTS.md](https://github.com/TraceMachina/nativelink/blob/main/AGENTS.md): the repository map for an agent working on the code: what each crate owns, where to change what, and which doc has to follow each kind of change.

## Optional

- [NativeLink on GitHub](https://github.com/TraceMachina/nativelink): source, issues, releases.
- [Remote Execution API](https://github.com/bazelbuild/remote-apis): the protocol NativeLink implements.