Adding Machines

Concise lifecycle overview for bringing a new machine into the Clan. The full step-by-step (config templates, profiles, secret matrix, decryption keys) lives in the New Machine Setup Guide — this page is the map, not a duplicate.

The repo is dendritic: features are flake.modules.{nixos,darwin,hjem}.<feature> and machines are composed from them by the registry in modules/clan/. A machine is therefore wired in a few small places rather than one big configuration.nix.

Lifecycle at a glance

1. Create the host module — modules/hosts/<name>/default.nix (host-specific config + hardware; templates in new-machine-setup).
2. Provide hardware info (NixOS only) — facter or hardware-configuration.nix, imported by the host module (see below).
3. Register in the modules/clan/ registry (see below).
4. Add the machine to the secret matrix — lib/machine-env-matrix.nix.
5. Set up decryption keys — clan vars keygen on the machine + clan secrets machines add <name>.
6. Generate secrets — clan vars generate --machine <name>.
7. Validate & deploy — just check, then clan machines update <name>.

Steps 4, 5, 6 are detailed in new-machine-setup.

Register in the modules/clan/ registry

A machine is wired in up to four files (all under modules/clan/):

1. default.nix — fleet roster. Declare the host platform and inventory entry:

   # clan.machines.<name> (host platform — required for the mixed darwin+linux fleet)
   clan.machines.<name>.nixpkgs.hostPlatform = "x86_64-linux"; # or aarch64-darwin / x86_64-darwin
   
   # clan.inventory.machines.<name> (deploy target, class, tags)
   inventory.machines.<name> = {
     # Darwin only: machineClass = "darwin";
     deploy.targetHost = "root@<name>.local";   # luxus@<name>.local for Darwin
     tags = [ "nixos" "workstation" ];           # or darwin / server / laptop / gpu-nvidia ...
   };

2. machines.nix — feature registry. Import the host module + the flake.modules.{nixos,darwin}.* features the machine needs:

   clan.machines.<name>.imports = [
     ../hosts/<name>          # host-specific config + hardware
     nixos.common             # (nixos = config.flake.modules.nixos)
     nixos.avahi-mdns
     # ...features this host gets
   ];

3. hjem-users.nix — hjem user. Compose the user’s hjem profiles + packages via the mkUser helper (profiles are hjem.<profile> namespaces).

4. services.nix — clan services. Add the machine to the relevant inventory.instances (explicit roles.*.machines.<name>); tag-based assignments (tags.nixos, tags.all) apply automatically from the roster tags.

Existing machines for reference: lea (nixos, workstation, desktop, gpu-nvidia), vanessa (nixos, server, homelab, gpu-nvidia), emily and zoe (darwin, laptop).

Hardware: facter (preferred) or hardware-configuration.nix

This repo prefers nixos-facter. The host module imports it explicitly (clan no longer auto-imports machines/<name>/ — that directory is gone):

## modules/hosts/<name>/default.nix
imports = [
  inputs.nixos-facter-modules.nixosModules.facter
  { config.facter.reportPath = ./facter.json; }
  ./disko.nix   # declarative partitioning, if used (lea/vanessa have one)
];

Generate the report on the target and commit it into the host directory:

## On the new NixOS machine
sudo nix run nixpkgs#nixos-facter -- -o facter.json
## copy it to modules/hosts/<name>/facter.json and commit

Alternative (legacy): generate hardware-configuration.nix with nixos-generate-config and import ./hardware-configuration.nix instead.

The nixos-facter module emits a “‘system’ has been renamed” eval warning from upstream — harmless, expected.

Validate and deploy

just check                       # deadnix, statix, nixfmt --check, conventions, nix flake check
scripts/validate-inventory.sh    # confirm the inventory is consistent
clan machines update <name>      # build + activate on the target (= just update <name>)

See Testing Strategy for build/eval steps before deploying, and Removing a Machine for the reverse.