nimmo/nixos-config
nimmo/nixos-config
Watch
1
0
Fork
You've already forked nixos-config
 0
Code Issues 15 Pull requests Wiki Activity Actions
Page: 56 SpecialArgs and Home Manager Argument Flow
Pages
00 Documentation Map and Scope 00 Documentation Standards 00 Start Here and Governance 10 System Atlas 11 Fleet Overview 12 Host Inventory 13 Service Catalogue 14 Network and Access Topology 15 Storage and Data Map 16 Automation and Control Plane 20 Architecture Decisions 21 ADR 001 Electra Hardware Specialisations 22 ADR 002 Workload Placement 23 ADR 003 Network Exposure 23 Project Tracking 24 ADR 004 Engram Durable Agent Memory 24 Security Baseline 25 ADR 005 Auto Update Control Plane 26 ADR 006 Scoped Secret Files 30 Operations and Runbooks 31 Routine Fleet Operations 32 Safe Testing and Deployment 33 Host Provisioning 34 Monitoring and Service Investigation 35 Backup Verification and Partial Restore 36 Full Host Recovery 37 Electra Boot Trust Recovery 38 Secret Editing and Recipient Rotation 39 Auto Update Incident Response 39a Service Migration and Cutover 39b Wrapper Repository Packaging 40 Engineering Handbook 41 Repository Structure and Import Chain 42 Configuration Ownership Boundaries 43 Adding Packages and Flake Inputs 44 Adding a Module or Profile 45 Adding a Host 46 Adding or Migrating a Service 47 Testing and CI Contracts 48 Secrets Implementation Conventions 49 Documentation Maintenance 50 NixOS Learning Path 51 Guided Repository Tour 52 Nix Language Essentials 53 Declarative Configuration Store and Generations 54 Flakes and Inputs 55 NixOS Modules and Option Merging 56 SpecialArgs and Home Manager Argument Flow 57 Electra Specialisations Worked Example 58 Nix Troubleshooting Primer 90 Historical Material 91 Electra Secure Boot Hardening Record Home
1 56 SpecialArgs and Home Manager Argument Flow
Nimmo edited this page 2026-09-13 13:07:16 +01:00
Table of contents

specialArgs and Home Manager Argument Flow

  • Type: Tutorial
  • Status: Current
  • Scope: How the shared flake builder passes inputs and host context into NixOS and Home Manager modules
  • Canonical sources: flake.nix; hosts/vega/default.nix; modules/services/redview.nix; modules/profiles/ai-agents.nix; home/users/nimmo/default.nix; Home Manager NixOS module manual
  • Last verified: Source commit 556df88494686003b1c4f20c8e0b99b5afc16a6e (2026-09-12); source HEAD b2831d33132967b4c4fb69e6068b2b05fff8fdff changes only flake.lock. Argument definitions and consumers checked 2026-09-13; no module changed.
  • Review triggers: makeNixosSystem, specialArgs, home-manager.extraSpecialArgs, primary-user path, host role metadata, or Home Manager module composition

Learning goal and prerequisites

Trace an external flake input and host-derived values to the module function that uses them, without confusing the NixOS and Home Manager argument scopes. Read Flakes and Inputs and NixOS Modules and Option Merging first. The Home Manager manual is the upstream reference for its NixOS-module integration.

The NixOS path

flake.nix captures all inputs as inputs in the outputs function. The shared makeNixosSystem builder passes them into NixOS evaluation with:

specialArgs = { inherit inputs; };

inherit inputs; means inputs = inputs;. Any NixOS module function that needs a root input can accept it, for example { config, inputs, lib, pkgs, ... }: in modules/services/redview.nix. That module imports inputs.redview.nixosModules.default and selects its package for the host platform. Other modules need not list inputs.

specialArgs adds a function argument; it does not automatically enable the module, place its package on every host, or decrypt any secret. A host must import the relevant module and satisfy any enable gate. The package output shape is specific to that input, as Adding Packages and Flake Inputs explains.

The Home Manager path

The same makeNixosSystem builder imports the matching Home Manager NixOS module and sets:

home-manager.users.${config.nixosConfig.primaryUser} =
  import ./home/users/${config.nixosConfig.primaryUser};

This creates the per-user Home Manager module from the configured primary user's directory. The builder sets home-manager.useGlobalPkgs = true, so Home Manager uses the host package set. It also contributes Plasma Manager through home-manager.sharedModules and passes the following arguments to Home Manager modules through home-manager.extraSpecialArgs: inputs, isServer, flakeRepo, primaryUser, userEmail, and hostName. Here isServer is derived from config.nixosConfig.host.role == "server"; it is not an extra flake-output parameter or a guess from the hostname.

home/users/nimmo/default.nix accepts isServer and primaryUser. It adds ./plasma.nix only when !isServer, and uses primaryUser for home.username and home.homeDirectory. Changing the primary user therefore requires a matching home/users/<name>/ entry point, not just a new name in host metadata. The module's home.stateVersion is its own persistent compatibility setting, separate from system.stateVersion.

The NixOS and Home Manager scopes are connected but not identical. The NixOS specialArgs does not, by itself, feed nested Home Manager modules; the explicit extraSpecialArgs does that. A NixOS module such as modules/profiles/ai-agents.nix may accept NixOS inputs and set home-manager.users options, while a file under home/users/nimmo/ is evaluated as a Home Manager module and receives its own argument set. Do not copy code between those locations assuming the same config, options, or arguments.

Guided check

Follow inputs.redview from flake.nix to the NixOS Redview module and Lyra's host import. Separately, follow isServer from the Lyra host role through home-manager.extraSpecialArgs to the conditional Plasma import in home/users/nimmo/default.nix. Explain why neither trace depends on the other. Then find a home/users/nimmo/ module that accepts inputs and identify which extra-argument declaration makes that possible.

If an argument is undefined, inspect the function header and the appropriate builder argument path first. If a Home Manager module is missing, inspect the selected primary-user directory and imports list, then use Repository Structure and Import Chain. Do not fix a missing argument by placing a second, divergent flake input inside a user module.