nix-cache-beacon: Best Nix Cache Tool for NixOS Users in 2026

What Is nix-cache-beacon?

nix-cache-beacon is a NixOS module from adisbladis that adds mDNS service discovery for Nix binary caches and races substitute requests against caches announced on the local network. nix-cache-beacon is one of the best Nix Binary Cache Tools for NixOS operators, and the repo’s example shows it exposing a Harmonia cache on port 5000 while serving local substitutes through localhost:5028.

The point is simple: make every Nix node on the LAN aware of nearby caches without a central coordinator. It is still a signed-substitution system, so it fits the normal Nix trust model instead of inventing a new one.

Quick Overview

Who Should Use nix-cache-beacon?

• NixOS homelab owners who want nearby machines to share builds without standing up a separate cache appliance.
• Platform engineers managing multiple Linux hosts that repeatedly evaluate the same derivations and can benefit from LAN-local substitution.
• Self-hosting teams that already run Harmonia or another cache backend and want cache discovery on top of it.
• Indie hackers running small fleets where reducing redundant rebuilds matters more than building a full artifact registry.

Not ideal for:

• Teams that need an Internet-facing, centrally managed binary cache with dashboards, quotas, or org-level governance.
• Environments that require encrypted transport for every cache lookup, because nix-cache-beacon traffic is explicitly unencrypted.
• Users who do not control their LAN topology, since mDNS discovery is a local-network feature rather than a cross-region distribution layer.

Key Features of nix-cache-beacon

• mDNS-based cache discovery — nix-cache-beacon advertises and discovers caches with multicast DNS, so Nix hosts on the same subnet can find each other without static substituter lists. That cuts down on manual host inventory and lets cache participation follow the network.
• Cache racing — nix-cache-beacon races substitute requests against discovered caches and returns the first usable match. In practice, that means a local node can answer before a slower remote cache, which is exactly what you want for repetitive nix build and nixos-rebuild workflows.
• Signature-first trust model — nix-cache-beacon does not weaken Nix substitution security. Packages still need to be signed by a trusted key, and package signatures are checked before metadata is returned during a race.
• NixOS module integration — the primary workflow is declarative configuration in NixOS, not ad-hoc daemon management. That makes it easy to keep cache advertising, firewall ports, and local substituter settings in the same flake or system config.
• Backend-agnostic cache support — the README explicitly says nix-cache-beacon can be used with any cache implementation, and the example uses Harmonia. That means the discovery layer is decoupled from the backend that actually serves the store paths.
• Local-network scope — nix-cache-beacon is intentionally scoped to the LAN, which keeps the setup simple and makes latency predictable. The trade-off is that it is not a public cache mesh or CDN replacement.
• Explicit privacy trade-off — traffic is unencrypted, and the project calls out the privacy implications directly. That is useful because you know upfront that neighboring hosts can observe substitute activity on the wire.

nix-cache-beacon vs Alternatives

Pick Cachix when you want a hosted workflow, team sharing, and less infrastructure to operate. Pick Attic when you want a self-hosted artifact layer with stronger central control than LAN discovery provides.

Pick Harmonia when you need a straightforward cache server and already know which host should publish it. Pick nix-cache-beacon when the better answer is not a bigger cache, but discovery across machines that are already on the same network.

If your rollout process already uses djevops for deployment scripting or MachineAuth for host identity, nix-cache-beacon fits as the cache-discovery layer rather than the policy layer. For test environments or cloud-like host simulations, awsim can help you validate the machine side before you expose cache ports.

How nix-cache-beacon Works

nix-cache-beacon sits between Nix’s normal substituter flow and whatever cache backend you already run. It announces cache availability with mDNS/DNS-SD, listens for peers on the local network, and then races requests across the discovered endpoints while keeping Nix’s signature checks intact.

The architecture is intentionally small: one part advertises a cache, one part discovers caches, and one part exposes a local substituter endpoint that Nix can talk to. That is why the example config wires nix.settings.substituters to http://localhost:5028, while the cache backend itself can still be Harmonia on port 5000.

{ ... }:
{
  services.nix-cache-beacon = {
    advert = {
      enable = true;
      port = 5000;
    };

    cache.enable = true;
  };

  nix.settings.substituters = [ "http://localhost:5028" ];

  services.harmonia.cache.enable = true;
  networking.firewall.allowedTCPPorts = [ 5000 ];
}

That configuration advertises a cache, turns on local cache use, and opens the backend port that serves store data. After activation, Nix will try the local beacon endpoint first, and the beacon will race the nearby caches it discovers on the LAN.

Pros and Cons of nix-cache-beacon

Pros:

• Keeps the standard Nix trust model intact by requiring trusted signatures before metadata is returned.
• Reduces redundant rebuilds across hosts that repeatedly realize the same derivations.
• Works with existing cache backends instead of forcing a new storage format or registry.
• Declarative NixOS integration makes rollout reproducible across machines and flakes.
• Low operational footprint because it relies on local-network discovery rather than a central control plane.
• Good fit for homelabs and small fleets where the network is already trusted and latency matters.

Cons:

• Alpha status means you should expect rough edges and incomplete ergonomics.
• Unencrypted traffic is a real privacy issue on shared networks.
• Local-network only limits usefulness for multi-region or Internet-distributed caches.
• No built-in hosted control plane for user management, analytics, or cache policy.
• Requires NixOS or equivalent manual wiring if you are not using the module path.

Getting Started with nix-cache-beacon

The fastest path is to add the NixOS module, enable advert and cache mode, point Nix at the local substituter, and rebuild the system. The project’s README shows the backend on port 5000, the beacon endpoint on 5028, and Harmonia serving the actual store data.

# edit your NixOS config or flake module
sudo nixos-rebuild switch

After the switch completes, the machine begins advertising its cache over mDNS and can consume caches discovered on the LAN. If you are opening ports in a firewall, make sure the backend port is reachable by peers and verify that your trusted signing keys match the caches you expect to use.

Verdict

nix-cache-beacon is the strongest option for local Nix cache discovery when you already run NixOS hosts on the same LAN. Its best strength is peer-discovered substitution with signature checks preserved; its biggest caveat is unencrypted traffic and alpha status. Use it if you want LAN-local cache speedups, not a hosted cache platform.