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@f0fb9b2d926a32b10c543e92093ba00c5a291b79 # v1.33.0
  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

Released real-client coverage proves cold publication and fresh-store substitution. No comparative Nix result is promoted yet.

Nix cache page All benchmarks

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.