Skip to content
Documentation

Docs / Adapter commands / Nix

Nix adapter

Give Nix a runner-local binary-cache endpoint while Nix continues to handle derivations, closures, NAR files, substitution, and signatures.

Command
boringcache nix
Protocol
Nix HTTP binary cache with substituter and post-build publication
Action
mode: nix

How the adapter works

Nix-native substitution

Nix still handles derivations, closures, NAR files, store identities, and substitute selection.

Publication stays off the build loop

The post-build hook queues completed output paths; a bounded worker batches publication and drains before the adapter exits.

Scoped trust

Global signature checks stay enabled; trust is limited to the loopback store used for the invocation.

Set up Nix

Install Nix first, keep the cache tag in .boringcache.toml, then wrap the ordinary Nix command. The adapter adds a loopback substituter and drains completed outputs before it exits. Global Nix signature checks remain enabled.

[adapters.nix]
tag = "nix-cache"

# Run: boringcache nix -- nix build .

Before the first run

  • Install Nix on Linux or macOS before running the adapter.
  • For a daemon-backed multi-user install, add the runner user or one of its groups to trusted-users.
  • Keep global signature checks enabled; trust is scoped to the loopback store used for this invocation.

Use the same adapter in GitHub Actions

The Action starts the Nix adapter for later steps. Nix must already be installed on the Linux or macOS runner.

.github/workflows/ci.yml
- uses: boringcache/one@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  with:
    trust-policy: auto
    mode: nix

- run: nix build .

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

GitHub Actions reference

Benchmarks

Zed builds the same upstream commits with BoringCache and Cachix on the same runner classes.

Zed

Nix

Benchmark →

Code editor written in Rust.

Average restore, build and save · lower is better

GitHub runner

4 vCPU · 16 GB · Ubuntu 24.04 x86-64

BoringCache
1 h 7 min 30 builds
Cachix
1 h 4 min 30 builds
Same CPU model

Builds of one commit can land on different CPU models. These ratios use only the build pairs where both caches ran on the same model; above 1.00× means BoringCache's total time over those pairs was lower.

Cachix vs BoringCache
0.99× · 12 of 30
6 CPU models recorded
BoringCache · Binary cache
AMD EPYC 7763 (18 builds) · Intel Xeon Platinum 8573C (4 builds) · Intel Xeon Platinum 8370C (3 builds) · AMD EPYC 9V45 (3 builds) · AMD EPYC 9V74 (2 builds)
Cachix
AMD EPYC 7763 (13 builds) · AMD EPYC 9V74 (5 builds) · Intel Xeon Platinum 8573C (5 builds) · AMD EPYC 9V45 (4 builds) · Intel Xeon Platinum 8370C (2 builds) · Intel Xeon 6973P-C (1 build)
Cold and warm builds

Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.

One cold and warm build per cache
Cache Cold Warm CPU
BoringCache Binary cache 1 h 8 min 4 min 19 s Cold: AMD EPYC 9V45 · Warm: AMD EPYC 7763
Cachix 1 h 41 min 4 min 1 s Intel Xeon Platinum 8573C Different CPU

Cache hits

BoringCache · GitHub runner · 4 vCPU

96.2% of 179,564 lookups over 30 builds

Served from the runner
Under 1 ms per read
Read from cache
41.7 GB

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

Compare every supported command, protocol, and Action mode in one place.

Adapter command index →

Need help or found something unclear? Open an issue or browse the CLI repo.