Skip to content

Binary caches

Chooser for three roles: substitute (client pulls prebuilts via substituters / keys), host (serve or publish a store: nix-serve, Harmonia, Attic, Cachix, S3/file://), sign (Ed25519 secret on the write path; clients list the public half in trusted-public-keys). Not a full client/hosting/signing tutorial—use the linked leaves. Client knobs: nix.conf knobs. Wire format: Substitutes and NAR info.

Decision table

Situation Prefer Leaf Avoid if…
Only need public Nixpkgs / NixOS prebuilts Default https://cache.nixos.org/ + its key Binary caches You also need private/org paths that are never on that cache
Add a private / third-party cache on clients extra-substituters + matching extra-trusted-public-keys; allow-list in trusted-substituters for unprivileged users Binary caches · Trusted users and substituters Replacing trusted-public-keys and dropping cache.nixos.org-1
Share one builder’s live /nix/store over HTTP nix-serve or Harmonia (+ sign key on server) Binary cache hosting Need durable multi-tenant storage; GC on the host removes substitutable paths
Durable self-hosted multi-tenant cache Attic (S3-compatible backend; server-side signing) Binary cache hosting You only want “HTTP from this builder’s store”; upstream still labels Attic an early prototype
Managed SaaS; minimal ops Cachix (cachix use / cachix push) Binary cache hosting · CI with Nix Must keep paths on your own infra only
Populate object storage or a directory tree nix copy --to 's3://…?secret-key=…' or file:///…?secret-key=… Binary cache hosting Expecting a live builder store without an upload/serve step
Create / place signing keys nix-store --generate-binary-cache-key; secret only on signer/host Signing and caches Distributing the secret to every client
CI / Hydra should feed a project cache Build → push (cachix / attic / nix copy); clients only substitute CI with Nix · Hydra Committing write tokens or signing secrets
Several hosts share private caches (hub + builders + laptops) Hub durable cache + edge Harmonia; wire extra-substituters / keys / builders-use-substitutes per role Private cache mesh Treating VPN membership as binary trust, or relying only on live-store edges after GC
Untrusted user / “just turn off sigs” Keep require-sigs = true; use trusted-substituters + keys (or a trusted user) Trusted users and substituters · Signing and caches require-sigs = false / store trusted=true without understanding binary authenticity

Remote builders pulling their own caches: builders-use-substitutes — Remote builders. Binary authenticity vs daemon privilege: Inter-machine trust.

Failure callouts

Symptom / mistake Fix
Unprivileged user: substituter ignored / “untrusted substituter” URL must be in daemon trusted-substituters, or the caller in trusted-users (Trusted users and substituters)
Substituter URL set but no matching trusted-public-keys Add the cache’s public key (extra-trusted-public-keys); with require-sigs on, unsigned/non-matching sigs reject non-CA paths (Signing and caches)
Set trusted-public-keys = my-cache-1:… and lost cache.nixos.org That setting replaces the default list—keep cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= (or use extra-trusted-public-keys)
Confusing trusted-users with signatures trusted-users = who may configure substituters / import unsigned; trusted-public-keys = which NAR signatures count—orthogonal (Trusted users and substituters)
require-sigs = false (or store trusted=true) to “make the cache work” Prefer signing + client keys; disabling checks trusts whoever can write that cache (Signing and caches)
Cache miss vs download failure Miss → local build. Failed fetch of a known substitute only falls back if fallback is true (default false)—Binary caches · nix.conf knobs

See also

References