Skip to content

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

Open
tashian wants to merge 1 commit into
mainfrom
carl/nixos-module-step-agent
Open

Add the step-agent NixOS module, and align with the upstream NUR layout#17
tashian wants to merge 1 commit 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.

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 ];
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