For agents
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.
Who this is for: an AI agent (Claude Code, Cursor, Copilot, a homegrown tool) that has been pointed at NativeLink, and the person pointing it. What you'll have at the end: the entry points, a procedure for reading the whole corpus in order, the conventions that make pages citable and verifiable, and a task index into the rest of the docs. Time: five minutes to read, one fetch to load everything.
Read this first if you are an agent
- Fetch
/llms-full.txt. It is the entire documentation corpus, every page body verbatim, in reading order, in one plain-text file (under 1 MB). One fetch gives you everything a human would find by clicking through the sidebar. - If you only want the map, fetch
/llms.txtinstead: one line per page with its canonical URL and a one-sentence description, in the same order. - Each page in
llms-full.txtstarts with a line of the form# https://docs.nativelink.com/<path>. That is the page's canonical URL. Cite it, and cite headings with the explicit#anchoryou see in the source (## Heading [#anchor]), because those anchors never move. - Three pages are generated from the source code and are linked rather than
inlined, because they are long and change on a different cadence. Fetch
them directly when you need them:
/reference/nativelink-config: every configuration field, its type and default, for the latest release; older releases live at/reference/nativelink-config/v1.x.yand the development branch at/reference/nativelink-config/main./reference/metrics: every OpenTelemetry instrument, its attributes, and whether the binary actually emits it./reference/changelog: the release history.
- When a page states how the binary behaves, look for a source link: in the
page source it is
<SourceLink file="path/in/repo" symbol="name" />, and in rendered HTML an<a data-source-link="path/in/repo" data-source-ref="vX.Y.Z">. It resolves tohttps://github.com/TraceMachina/nativelink/blob/<ref>/<path>. Follow it to check the claim against the code at that tag before you rely on it. - The current release these docs describe is the
data-source-refvalue, and the config reference and metrics reference both name the version and commit they were generated from in a comment at the top of the page.
Nothing here requires an account, an API key, or JavaScript: every URL above serves plain text or static HTML.
The three entry points
AGENTS.md at the repo root AGENTS.md is for an
agent working on the code. It maps every nativelink-* crate to what it
owns, says where config, store, scheduler and worker logic actually live,
gives the build and test commands, and carries a table of "you changed X, so
this doc has to follow" pairs that are often missed.
/llms.txt is for an agent working with the docs. It
follows the llms.txt convention: a link-first index of
every published page with a one-line description, in reading order. It is
generated from the navigation and page frontmatter by
gen-llms.mjs, runs as part of
dev and build, and is gitignored, so it cannot be edited into
disagreement with the sidebar, because there is no committed copy to edit.
/llms-full.txt is the same corpus with bodies
included, concatenated in the same order, for agents that would rather fetch
once than crawl every page. Page bodies are reproduced verbatim, MDX
components included, so nothing is lost in transcription.
How the corpus is ordered
The sidebar, llms.txt and llms-full.txt all use the same order, defined
once in the meta.json files under content/docs/:
| Section | What it is | Read it when |
|---|---|---|
| Why NativeLink | What a remote cache and remote execution do, and who benefits | Deciding whether to use it at all |
| Getting started | A cache running, connected to a build, proven to be hitting | First contact |
| Remote execution | Workers running the actions the cache misses | After the cache works |
| Configuration | The config model: stores, servers, services, scheduler, workers | Writing a config rather than copying one |
| How-to guides | Task recipes: every storage backend, TLS, multiple workers, upgrades, migration | A specific task |
| Operate | Production shape, deployment, observability, scaling, runbooks, troubleshooting | Running it for other people |
Concepts (/explanations/...) | How it is built: architecture, stores, scheduler, worker, correctness, LRE, history | Understanding a behaviour |
| Reference | Generated config and metrics references, CLI and environment, protocol, glossary, licence, changelog | Looking something up |
Contribute (/contribute/...) | Building, testing, the crate map, extending, releasing, working on these docs | Changing the code or the docs |
Pages in the first six sections open with a <Prerequisites> block
(data-prerequisites in HTML) stating what they assume you already have, and
end with one primary <NextStep> (data-next-step="next") naming the page
that follows; detours are data-next-step="aside". Concepts, Reference and
Contribute carry no position: enter them from a search or a link.
Task index
The shortest path from a question to the page that answers it.
| If the task is | Read |
|---|---|
| Run NativeLink for the first time | Quickstart, then Verify your cache |
| Point Bazel, Buck2, Siso, Chromium, Pants, BuildStream or CMake at it | Connect your build |
| Share one cache across a team | Shared cache |
| Add workers and run actions remotely | Remote execution, Your first remote action |
| Route actions to the right workers | Platform properties |
| Hermetic toolchains, containers, persistent workers | Toolchains and hermeticity, Containers and images, Persistent workers |
| Understand or write a config file | Configuration, then the generated reference |
| Pick and configure a storage backend | Storage backends |
| Compose stores (tiers, verification, dedup, compression, sharding) | Compose stores, Store model |
| TLS, mTLS, identity headers | TLS and auth |
| Upgrade or migrate | Upgrade versions, Migrate an existing cache |
| Production shape, deployment, security | Production configuration, Docker Compose, Bare metal, Security hardening |
| Metrics, dashboards, alerts | Observability, Metrics reference |
| Scale workers or the CAS | Scaling workers, Scaling the CAS, Autoscaling reference |
| Something is wrong | Troubleshooting, Runbooks |
| Every flag, environment variable and CLI argument | CLI and environment |
| Which RPCs and protocols are implemented | Protocol and API |
| What is open source and what is licensed differently | Open source and Enterprise |
| How the scheduler, worker and stores work internally | Architecture, Scheduler internals, Worker execution |
| Build, test or change the code | Contribution guidelines, Repository and crate map, Codebase internals, How to extend |
| Change these docs | Working on the documentation |
What these docs guarantee to a machine reader
Each of these is enforced by something in the repository, not by an author remembering. Where it is a script, the script is named.
One canonical page per concept. If two pages would explain the same thing, one of them links the other. An agent that finds an answer has found the answer.
Stable anchors. Every heading and every FAQ entry carries an explicit
[#anchor] or id, so a citation to a specific claim keeps resolving after
the prose around it is reworded.
fails the check if one is missing, and its --fix writes the anchor Fumadocs
would have derived from the heading text anyway, so pinning an anchor never
moves a link that already worked.
Redirects on every moved URL. This site's structure changed substantially; agents hold cached URLs longer than humans hold bookmarks, so old paths redirect rather than 404. They live in next.config.mjs. Follow redirects rather than treating a 301 as a failure.
Doc-to-source permalinks. Behavioural claims carry a link to the code
that implements them, pinned to a release tag rather than to main. A
permalink that drifts is worse than no link, because the reader can't tell.
The pinned ref is a single constant in
source-ref.ts.
Generated reference. The configuration reference, the metrics reference and the changelog are generated from the source of truth in the repo rather than transcribed from it. An agent reading the docs and an agent reading the code get the same answer by construction. Config snippets in narrative pages are checked against that generated reference by lint-snippets.mjs, so a snippet cannot quietly reference a field that no longer exists.
Every internal link resolves, and every page on the path has a next step. lint-links.mjs and lint-navigation.mjs run on every change, so a crawl never hits a dead internal link or a dead end.
Machine-detectable structure. Verification blocks carry
data-verify-block; prerequisite blocks carry data-prerequisites; next
steps carry data-next-step; version badges carry data-min-version; source
links carry data-source-link and data-source-ref. Ordering and
provability are readable without parsing prose.
What is not guaranteed
Being specific about the edges is more useful than a blanket claim.
Prose is not generated. Everything outside the generated reference is
written by a human and checked against the source at the pinned release, not
by a script. A behavioural claim carrying a <SourceLink> has been checked
against that file at the pinned tag; a claim without one has not been
mechanically checked against anything.
The pinned ref lags releases. <SourceLink> targets a release tag, so
immediately after a release lands the links point at the previous one until
the reference is regenerated. That is the deliberate trade: a stale-but-honest
permalink over a main link that silently means something different next
week.
Third-party tools are described from their own documentation. Bazel, Buck2, Siso, Pants, BuildStream and recc flags are taken from those projects' docs at the time of writing; NativeLink's source cannot vouch for them.
NextGetting startedIf you're here to actually run NativeLink rather than to point something else at it, Getting started is the start of the reading path.