Glossary

Who this is for: anyone reading the rest of these docs who hit a word that was used as if it needed no explanation. What you'll have at the end: the one sentence you needed, and a link to the page that goes deeper. Time: use as a lookup.

Terms are alphabetical. Every heading has a stable anchor, so a link to a definition keeps resolving even if the wording around it changes.

Action

A single unit of build work. Encodes a command line, input file digests, the platform requirements, and the expected outputs. Hashing an action produces a stable identifier; identical actions have identical hashes.

Action Cache (AC)

A keyed store: hash(Action) → ActionResult. Cache hits skip the work entirely.

ActionResult

What an action produces. Output file digests, exit code, captured stdout/stderr, timing metadata.

Awaited action

The scheduler's record of one action between Execute and completion: its current execution stage, its priority, and every client waiting on it. Two identical actions submitted at the same time join the same awaited action instead of running twice. By default this record lives in the scheduler process's memory (memory_awaited_action_db.rs), which is why two scheduler replicas behind a load balancer do not share in-flight work. See scheduler internals.

ByteStream API

The streaming transport for blobs too large to move in a single BatchUpdateBlobs or BatchReadBlobs call, with the digest encoded in the resource name. Where the batch calls stop and this one starts is a server limit the Capabilities API advertises.

Capabilities API

The RE-API service a client calls first, to learn which digest functions the server accepts and what its size limits are rather than assuming. See protocol and API surface.

CAS: Content-Addressable Storage

Stores every blob (source file, intermediate output, final binary) under the digest of its contents. The same byte sequence stored from anywhere collapses to one entry.

Completeness-checking store

An Action Cache wrapper that checks every output digest still exists in the CAS before serving a hit. Without it a CAS eviction turns old cache entries into hits that reference blobs nobody can download, and the build fails while fetching outputs instead of quietly missing the cache. Valid only on AC stores.

Dedup store

A store that splits blobs into content-defined chunks with FastCDC (fastcdc.rs) and stores each chunk once, so two versions of a large file that differ in the middle share everything else. The cost is an index lookup per read. See the store model.

Digest

A content hash plus a size. Used everywhere instead of file paths.

Digest function

The hash a client and server agree on for digests: SHA-256 or BLAKE3, negotiated per request rather than fixed at build time (DigestHasherFunc). Two clients using different functions produce different keys for the same bytes, so they do not share cache entries.

Eviction policy

The limits a store evicts against: max_bytes, max_seconds, max_count, and the evict_bytes low watermark that stops eviction thrashing right at the limit. Each defaults to 0, which means never evict on that dimension: a store configured without a policy grows until the disk does.

Execution stage

Where an action is in its life: CacheCheck, Queued, Executing, then Completed or CompletedFromCache (ActionStage). An action stuck in Queued has no free worker whose platform properties match what it asked for. CacheCheck is declared but the scheduler never reports it, because the cache lookup happens in a wrapper in front of the scheduler.

Existence cache store

A store that remembers which digests it has already confirmed exist, so repeated FindMissingBlobs calls stop re-querying the backend. It answers the existence question only; reads pass through.

fast_slow store

A two-tier store. Reads try the fast backend, fall back to the slow one, and copy what they find into the fast tier on the way back; writes mirror to both. Its one sharp edge: it never checks the slow tier for something the fast tier already has, so a blob that reached the fast tier without reaching the slow one stays invisible to everything reading the slow tier directly.

FindMissingBlobs

The CAS call that makes uploads incremental: the client offers a list of digests, the server returns the ones it does not have, and the client uploads only those. On a warm cache this and the AC lookup are most of what a client does.

Hermetic build

A build whose outputs depend only on its declared inputs. Same inputs → same outputs, on any machine, any time. What NativeLink does and does not guarantee here is in correctness and hermeticity.

Input root

The complete file tree an action is allowed to see, encoded as a Merkle tree of Directory messages that reference their files and each other by digest. Its root digest is part of the action hash, so changing one input file changes the cache key.

Instance name

A namespace inside a NativeLink cluster. Each service entry maps an instance name to a store or scheduler, so one cluster can serve multiple isolated environments, and the scheduler keys in-flight actions by instance name as well as digest. Two instance names that point at the same store share its contents.

InstanceName

Isolation

Keeping an action from seeing state outside its declared inputs. On Linux, workers can isolate actions with kernel namespaces via the use_namespaces and use_mount_namespace worker options, which also reap zombie processes and improve hermeticity. NativeLink doesn't currently integrate external sandboxing tools like bwrap, landlock, or sandbox-exec.

use_mount_namespace

JSON5

The dialect NativeLink's configuration file is written in: JSON plus comments, trailing commas, and unquoted keys. Every example in the configuration reference is JSON5.

LRE: Local Remote Execution

Building your toolchain with Nix so that your local build and your remote workers invoke the same toolchain binaries, at the same /nix/store paths, which makes their action digests match and lets both share one cache. No worker runs on your laptop. See LRE.

Operation

The handle a client holds on a running action, from google.longrunning.Operation. Execute returns one immediately and the client watches it for stage changes; WaitExecution re-attaches to it after a disconnect, which is what stops a dropped connection from re-running the work.

Origin events

An experimental stream of the requests and responses a server handled, published to a store for an external consumer to read (events.proto). Off unless experimental_origin_events is configured.

Platform properties

Key/value tags attached to an action ("this action needs Linux, x86_64, a GPU") and to a worker ("this worker has Linux, x86_64, a GPU"). The scheduler matches them.

is_satisfied_by

Priority

An integer on ExecuteRequest's execution_policy; NativeLink dequeues the highest value first when workers are scarce (the RE-API leaves the direction to the server, and its suggested default is the reverse). It orders the queue and nothing more; an action already executing is not interrupted for a higher-priority one that arrives after it.

AwaitedActionSortKey

Remote Execution API (RE-API)

The standard gRPC protocol every supported build system speaks. Spec.

Scheduler

The dispatcher. Receives Execute calls, picks workers, tracks in-flight actions.

Shard store

A store that routes each key to one of several backends by digest hash, with a weight per backend. It spreads capacity; it is not replication, so losing one backend loses that backend's share of the data rather than none of it.

Store

NativeLink's unit of storage configuration: a named thing that gets and puts bytes under a key. Stores compose, because a store's backend is another store, so the CAS a server serves is usually a stack of wrappers over one real backend. See the store model.

Toolchain

The bundle of binaries an action needs to run: compiler, linker, standard library, etc. See how toolchains are provided.

Verify store

A wrapper that, depending on verify_size and verify_hash, checks a blob's size and re-hashes it on write, failing the upload when the bytes do not match the digest they were offered under. It turns silent corruption into a write error. Both checks belong on CAS stores and neither belongs on an AC store.

Worker

The process that runs an action. Fetches inputs from CAS, runs the command, uploads outputs to CAS.

Worker API

NativeLink's own gRPC service, not part of the RE-API, over which a worker registers with a scheduler and receives work (worker_api.proto). One bidirectional ConnectWorker stream carries the whole conversation, which is what keeps a worker talking to the same scheduler instance even behind a load balancer.