herdr-nix

Official Nix packaging for Herdr's prebuilt GitHub Release binaries.

Contents

• Why this exists
• Usage
• Configuration / API
• Staying current
• Contributing
• Provenance
• Licensing

Why this exists

herdr's own documented Nix install instructions point at its source flake (nix run|build|profile install github:herdrdev/herdr/vX.Y.Z) — which builds herdr from source, pulling in the full Rust + Zig toolchain, on every install and every update. There's no binary cache behind it, so that source build repeats for every consumer, every time. That's especially unwelcome in a devenv context, where the shell can rebuild often.

This repo instead fetches herdr's own prebuilt, per-platform release binaries (herdr-linux-x86_64, herdr-linux-aarch64, herdr-macos-x86_64, herdr-macos-aarch64 — published by herdr's own release.yml on every tagged release) and wraps them in a Nix derivation. No compilation, no toolchain, just a hash-verified download.

Stable version updates are validated on all four platforms before being committed to main and published to the public Cachix cache (herdr). Only publishing jobs use the cachix environment credentials; preparation, validation, and pull requests do not.

Usage

With devenv

Add the flake input and pull the herdr Cachix cache declaratively — devenv wires the substituter and trusted public key for you, no manual nix.conf editing:

# devenv.yaml
inputs:
  herdr-nix:
    url: github:herdrdev/herdr-nix

# devenv.nix
{ pkgs, inputs, ... }:

{
  cachix.pull = [ "herdr" ];

  packages = [
    inputs.herdr-nix.packages.${pkgs.stdenv.system}.default
  ];
}

devenv shell then pulls herdr straight from the cache instead of building it.

Standalone Nix (flakes)

{
  inputs.herdr-nix.url = "github:herdrdev/herdr-nix";
  # ...
  # inputs.herdr-nix.packages.${system}.default
}

Or run it directly without adding an input:

nix run github:herdrdev/herdr-nix

To pull from the cache instead of building, add the substituter to your user/system nix.conf (or ~/.config/nix/nix.conf):

extra-substituters = https://herdr.cachix.org
extra-trusted-public-keys = herdr.cachix.org-1:3nH7IStRsS0ASfdonA0DCRR2ZrSCeWitZ7Kwew0cR4I=

Or, if you're consuming this as a flake input and have accept-flake-config = true set (or answer y to the one-time prompt), declare it in your own flake.nix instead so consumers of your flake pick it up too:

{
  nixConfig = {
    extra-substituters = [ "https://herdr.cachix.org" ];
    extra-trusted-public-keys = [ "herdr.cachix.org-1:3nH7IStRsS0ASfdonA0DCRR2ZrSCeWitZ7Kwew0cR4I=" ];
  };
}

To verify that key against the cache itself, run cachix use herdr (it writes the same substituter and key into your nix.conf), or read it straight from the API:

curl -s https://cachix.org/api/v1/cache/herdr

Configuration / API

This is a plain package flake — no NixOS/devenv module options, nothing to configure beyond picking a system. It exposes:

Output	Type	Notes
packages.<system>.herdr	derivation	The herdr binary, installed at bin/herdr.
packages.<system>.default	derivation	Alias for packages.<system>.herdr.
apps.<system>.default	app	nix run wrapper around bin/herdr.
checks.<system>.herdr	derivation	Same build, exercised by nix flake check.

Supported <system>: x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin — matching herdr's own published release assets. The pinned version and per-asset hashes live in package.nix; there is no override mechanism for the version — bump it via update.sh (see below) rather than overrideAttrs, since the hash is tied 1:1 to the pinned version.

Staying current

update.sh checks herdr's latest stable release (tagged vX.Y.Z; the frequent preview-* pre-releases are intentionally skipped) and rewrites package.nix with the new version and per-platform hashes. After publishing a stable release, Herdr triggers the update-check workflow here. It can also be run manually:

gh workflow run update-check.yml --repo herdrdev/herdr-nix --ref main

The workflow prepares one package update, runs nix flake check and the binary on all four platforms, then commits the validated package directly to main and publishes that exact commit to Cachix. No PRs, approvals, or scheduled polling are involved in the update itself. If validation fails, main stays unchanged. If main advances during validation, the push is rejected rather than rebasing untested changes; rerun the updater. If there is no version change, the workflow does nothing.

Cache publishing can be retried independently after a publishing failure:

gh workflow run publish.yml --repo herdrdev/herdr-nix --ref main

The Herdr-side trigger is non-blocking and uses a fine-grained token scoped to this repository's Actions write permission. This repository needs no write access to Herdr and does not need permission for Actions to create or approve PRs.

The commit job uses the repository-only NIX_UPDATE_DEPLOY_KEY secret after validation. Its SSH push triggers the separate publish workflow. GitHub's deploy-key exception to the update and PR rules applies to all writable deploy keys in this repository, so keep only the updater's key installed. Deploy keys cannot bypass the separate force-push, deletion, or linear-history protections.

To prepare and check an update locally:

./update.sh
nix flake check

Contributing

Issues and PRs are welcome, particularly reports of upstream release-asset changes or a Herdr version that breaks update.sh's detection.

Provenance

@tburny created this packaging and transferred it to the Herdr project in 2026. It remains a separate repository because it packages release binaries rather than building Herdr from source.

Licensing

This repo's own packaging code (flake.nix, package.nix, update.sh, CI) is MIT-licensed — see LICENSE. The herdr binaries this repo fetches and distributes are themselves licensed under AGPL-3.0-or-later by their upstream project; see Herdr's LICENSE for the terms that apply to the binary itself.