Shared cache

The source-available release of NativeLink is designed to run on your own infrastructure. This page covers what changes between the 10-minute quickstart and a deployment that serves your team without 3 AM pages.

When to self-host

Pick on-prem when one of these is true:

• Data residency. Build artifacts can carry source code, toolchains, even credentials. Self-hosting keeps them in whatever region or boundary you need (EU GDPR, US FedRAMP boundaries, air-gapped corp networks).
• Specialised hardware. GPU workers, ARM cross-compile fleets, in-house silicon. On-prem lets you use anything that can run a Linux binary.
• You already operate stateful services. If your team owns Kubernetes, Postgres, S3-compatible storage, adding NativeLink is marginal work.

If you'd rather not run it yourself, Enterprise offers a managed deployment; see Open source and Enterprise.

What ships in the box

A NativeLink deployment is composed of four roles. The same binary serves all of them; the JSON5 config decides which subset to run.

A single binary can run all four. For anything beyond a single developer, run them on separate processes so you can scale and restart each independently.

The rollout checklist

1. Pick the storage backend. The quickstart's basic_cas.json5 keeps everything under /tmp on one machine, which is fine for a 10-minute demo and useless for a team. Pick one before rolling out:

   • Filesystem: single-node clusters, sub-100GB caches.
   • Cloud object storage: anything multi-node. The experimental_cloud_object_store has providers for S3, R2, GCS, Azure Blob, ONTAP S3 and OCI; see S3 and compatible.
   • Redis: hot-key acceleration in front of the durable store. Optional but cheap latency wins.

2. Pick the deployment substrate. Most teams land on one of:

   • Kubernetes: Helm charts for Kubernetes ship with NativeLink Enterprise; the kubernetes/ directory in this repository holds only Kustomize building blocks used by its own examples.
   • Bare VMs: systemd units, one binary per role, with a load balancer in front. See Deploy on bare metal.
   • Docker Compose: a reasonable starting point for a handful of developers. See Deploy with Docker Compose.

3. Plan capacity. Heuristics from production clusters:

   • CAS storage: 5 to 20 GB per active developer, depending on language. C++ skews high; Go skews low.
   • Worker CPU: 1 vCPU per concurrent action. Headroom matters more than peak.
   • Network: cache reads are the hot path. Provision at least 1 Gbps between workers and CAS.

4. Set up TLS. TLS on every listener, and client certificates where the network is not trusted. The Production configuration page has the certificate layout and TLS and auth the per-hop settings.

5. Wire up metrics. NativeLink pushes OTLP metrics; there is no Prometheus scrape endpoint. Send them to an OpenTelemetry Collector and let Prometheus and Grafana read from there. See Observability.

Container registry

Official images are published to GitHub Container Registry. Pull a specific version tag; there is no latest tag to fall back on, and pinning is what you want in production anyway.

docker pull ghcr.io/tracemachina/nativelink:v1.6.5

The /pkgs/container/nativelink page lists every published tag.

Backups & recovery

The CAS is the only stateful piece you can't trivially rebuild from clients. Snapshot strategy depends on the backend:

• Filesystem: rsync or your filesystem's snapshot facility (ZFS, Btrfs). Restore by stopping the CAS, swapping the directory, starting again.
• S3-compatible: versioning + lifecycle policies handle the primary copy. For DR, cross-region replication.
• Redis: treat as ephemeral. Loss is a cache miss, not data loss.

The Action Cache can be wiped without data loss; you'll re-execute everything until it warms back up.

FAQ