Skip to content

Add the step-agent NixOS module, and align with the upstream NUR layout - #17

Merged
tashian merged 3 commits into
mainfrom
carl/nixos-module-step-agent
Aug 25, 2026
Merged

Add the step-agent NixOS module, and align with the upstream NUR layout#17
tashian merged 3 commits into
mainfrom
carl/nixos-module-step-agent

Conversation

@tashian

@tashian tashian commented Aug 24, 2026

Copy link
Copy Markdown
Member

Pairs with smallstep/agent#1200, which is where the module is maintained. Merge that one first or together — its mirror workflow targets nixos-modules/step-agent.nix, the path this PR creates.

Why

Installing pkgs.step-agent gets you the binary and nothing that runs it — no service, no system user, no PKCS#11 socket, no polkit rules. Customers have been getting that from files.smallstep.com/step-agent.nix, an object uploaded to S3 by hand on 2026-07-30 with no copy in any repo and no review on changes. It belongs beside the systemd units it translates, so smallstep/agent owns it as extra/step-agent.nix; this repository is where it becomes public and importable.

What's here

  • nixos-modules/step-agent.nix — the module, reconciled against the agent's current units (it now includes the PKCS#11 socket, and no longer orders the service after network-online.target, which was an EAP-TLS boot deadlock).
  • modules/nixos-modules/, modulesnixosModulesmodules/default.nix was still the untouched NUR template stub (one commit, "Initial commit"), and upstream nur-packages-template has since made this rename. Taking it now, while nothing depends on the old name, is cheaper than after we publish a URL.
  • ci.nix / overlay.nix — both carry isReserved = n: n == "lib" || n == "overlays" || n == "modules". Without moving these, ci.nix would treat nixosModules as a package and try to build it, and overlay.nix would splice it into the overlay as one.
  • flake.nix — exports nixosModules directly instead of only through legacyPackages.<system>. A NixOS module is the same expression on every platform and importing one shouldn't instantiate nixpkgs; this is what makes the import read imports = [ inputs.smallstep.nixosModules.step-agent ];.
  • README.md — a NixOS module section. The existing walkthrough installs the package and stops, so it left users with a binary and no running agent.

Verification

Evaluated against nixos-unstable in a nixos/nix container:

nixos-modules attrs:              [ "step-agent" ]
default.nix:                      { hasNixosModules = true; hasOldModules = false; }
ci.nix buildPkgs:                 32          # nixosModules filtered, not built
module via eval-config.nix:       renders step-agent.service + step-agent-pkcs11.socket

Note

This repository has no LICENSE — it's public, unlicensed, and about to be the canonical place we point NixOS customers at. Worth settling separately; upstream's template ships MIT, but that's a call for someone else to make.

dopey
dopey previously approved these changes Aug 25, 2026
Installing pkgs.step-agent gets you the binary and nothing that runs it: no
service, no system user, no PKCS#11 socket, no polkit rules. Customers have
been getting that from a hand-uploaded file on files.smallstep.com with no copy
in version control. It belongs beside the systemd units it translates, so
smallstep/agent owns it as extra/step-agent.nix and mirrors it here -- this
repository is where it is public, and where flake users can import it.

modules/ was still the untouched NUR template stub, so this also takes the
rename the template made since we forked it: nixos-modules/ and nixosModules,
which is the attribute consumers expect. Both reserved-name filters move with
it -- ci.nix would otherwise treat nixosModules as a package and try to build
it, and overlay.nix would splice it into the overlay as one.

flake.nix now exports nixosModules directly rather than through
legacyPackages.<system>, since a NixOS module is the same expression on every
platform and importing one should not instantiate nixpkgs. That is what makes
the documented import read

    imports = [ inputs.smallstep.nixosModules.step-agent ];
…tion

The module now takes services.step-agent.package; the README example pins
it to this repository's package so the daemon and the installed CLI stay
the same version. The module copy is byte-identical to
extra/step-agent.nix on the agent branch, as the mirror requires.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@tashian

tashian commented Aug 25, 2026

Copy link
Copy Markdown
Member Author

Follow-up from review: smallstep/agent#1202 fixes the module (package option so hosts can pin this repo's package, explicit bin/step-agent ExecStart since these derivations have pname step-agent-plugin and no meta.mainProgram, and list-merged allowUnfreePackages in place of the clobber-prone predicate). The last commit here syncs the mirrored copy byte-identically and documents the option in the README — merge order with the agent PR no longer matters for the module file.

Sync with the same wording fix on the agent branch: nixpkgs trails our
releases by however far behind the host's channel is, which stays true
once the package reaches a stable channel.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@tashian
tashian merged commit 1490cd7 into main Aug 25, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants