NixOS: declare the agent with services.step-agent; document edge releases - #552
Merged
tashian merged 6 commits intoSep 16, 2026
Conversation
…ases Rewrite the NixOS install section around one services.step-agent block: import the module, enable it, and declare team and fingerprint in settings. The rebuild installs the package, starts the agent, and the device enrolls on first start once it has been added via the API, so the interactive register step goes away for fleets. Interactive registration stays as the alternative for empty settings. Add an "Edge releases" subsection: point services.step-agent.package at an overrideAttrs of pkgs.step-agent with the edge tarball URL on packages.smallstep.com and the hex sha256 from the release manifest, which Nix accepts as-is. Name the error a TPM-less host hits, update the uninstall step, and note that on NixOS the unit's gate is ConditionPathExists=. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
With settings declared, agent.yaml is a store symlink, so document the --skip-config form of register, which registers the device without attempting to rewrite the declared file. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Srylax
suggested changes
Sep 3, 2026
"Everything it writes lives in /var/lib/step-agent" was too broad: the sockets go to /run/step-agent and `step-agent register` writes agent.yaml into /etc/step-agent. Say which directory each concern maps to instead. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NUdbhFjn3CCcyMAm8v33e6
The manifests on packages.smallstep.com now carry sha256_sri, so the snippet uses fetchurl's hash attribute with that value. Nix reports mismatches in SRI form, so a reader who pasted the hex form could not compare the two by eye. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NUdbhFjn3CCcyMAm8v33e6
Review pointed out that "settings is written to agent.yaml" reads as if the option writes the file in place. The module renders it into the store and links it at /etc/step-agent/agent.yaml so the daemon and the CLI find one file; say that. The edge snippet now shows 0.69.3, which is on the stable channel today but not yet in nixpkgs (0.69.2), so it is the case the section describes. Hash recomputed from the downloaded tarball and matches the manifest's sha256_sri. The troubleshooting-agent.mdx addition moves out of this PR: #549 carries the ConditionPathExists= wording now that agent#1205 shipped in 0.69.3. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
tashian
added a commit
that referenced
this pull request
Sep 15, 2026
Review on this PR asked for services.step-agent.settings rather than a hand-written environment.etc entry, and #552 rewrites the install section around exactly that. This PR keeps only the troubleshooting wording, which is now right for every platform: smallstep/agent#1205 shipped in 0.69.3, so current deb/rpm units report ConditionPathExists= too. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
tashian
enabled auto-merge
September 15, 2026 22:28
darkfronza
approved these changes
Sep 15, 2026
…-to-install-an-edge-release
tashian
deleted the
carl/eff-696-update-install-docs-showing-how-to-install-an-edge-release
branch
September 16, 2026 00:01
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes EFF-696.
Refs EFF-698: the stable-install rewrite is that issue's scope; it closes when the docs import the module from nixpkgs.
Rewrites the NixOS install section of the Smallstep Agent page and adds edge-release instructions. Replaces the
smallstep-agent.mdxhalf of #549 (itsenvironment.etcparagraph is subsumed bysettings). #549 carries thetroubleshooting-agent.mdxwording; agent#1205 shipped in 0.69.3, so this PR no longer touches that file.What changed
services.step-agentblock. Import the module, setenable = true, and declareteamandfingerprintinsettings.nixos-rebuild switchinstalls the package, starts the agent, and the device enrolls on first start once it has been added via the API. The interactivestep-agent registerstep is now the alternative for emptysettings, not the default.services.step-agent.packageat anoverrideAttrsofpkgs.step-agentwith the edge tarball URL onpackages.smallstep.comand thesha256_srihash from the release manifest.The
services.step-agentmodule withenable/settingsships fromfiles.smallstep.com/step-agent.nix(identical toextra/step-agent.nixat the agent v0.69.3 tag) and has the same option surface as the module proposed upstream in NixOS/nixpkgs#555971, so theimportsline is the only thing that changes once that lands.The
--skip-confignote exists becauseregistersilently drops a failed config write; that is filed as OFF-21.Verified
Followed the new section on a nixos-unstable aarch64 VM: install, all units enabled,
agent.yamlrendered fromsettings,step-agent versionoutput as shown, and the edge override switching the running agent to 0.69.2. The edge snippet now shows 0.69.3, the stable release nixpkgs does not have yet; its hash was recomputed from the downloadedstep-agent_0.69.3_linux_amd64.tar.gzand matches the manifest'ssha256_sri.The module change has shipped to
files.smallstep.com, so step 3'senable/settingsoptions exist for readers now.🤖 Generated with Claude Code