Add NixOS Machine Skill

Add NixOS Machine

This skill guides you through adding a new NixOS machine configuration following the dendritic pattern used in this repository.

Workflow Checklist

Copy and complete this checklist when adding a new machine:

[ ] 1. Pre-check: Run nix fmt && just lint && ncf eval all to ensure the configuration is clean before making changes
[ ] 2. Determine machine type: qemu-guest, lxc, or bare-metal
[ ] 3. Choose machine name: Should be unique and follow existing naming conventions
[ ] 4. Generate hostId: Run ./scripts/generate-hostid.sh from skill directory
[ ] 5. Add hostId to inventory: Edit inventory/host-id.nix
[ ] 6. Allocate IP (if needed): Edit inventory/networks/home.nix or skip for microvm/isolated machines
[ ] 7. Create machine module: Create modules/machines/<machine-name>.nix using examples from REFERENCE.md
[ ] 8. Stage new file: git add modules/machines/<machine-name>.nix
[ ] 9. Run validation: ncf eval nixos in a loop until clean
[ ] 10. Get stateVersion: Run the get-state-version script and add explicit value
[ ] 11. Run comprehensive validation: ncf eval all
[ ] 12. Format and lint: nix fmt && just lint
[ ] 13. Generate Tailscale auth key (if needed): ncf ts auth-key --machine <machine-name> then add secrets/<machine>/tailscale-auth to git
[ ] 14. Commit: Follow git workflow in CLAUDE.md

Machine Types

qemu-guest

Standard VM running in QEMU/KVM. Uses modulesPath + "/profiles/qemu-guest.nix".

Template: See REFERENCE.md for complete examples.

lxc

Proxmox LXC container. Imports self.nixosModules.lxc.

Typical imports:

imports = [
  self.nixosModules.baseline
  self.nixosModules.lxc
  self.nixosModules.binarin-baseline
];

bare-metal

Physical machine requiring hardware-configuration.nix.

Typical imports:

imports = [
  self.nixosModules.baseline
  (modulesPath + "/installer/scan/not-detected.nix")
  "${self}/my-machines/<machine-name>/hardware-configuration.nix"
  # ... other modules
];

Helper Scripts

generate-hostid.sh

Generates a random 8-character hex hostId:

files/claude-skills/add-nixos-machine/scripts/generate-hostid.sh

find-free-ip.sh

Finds the first available IP in a network:

files/claude-skills/add-nixos-machine/scripts/find-free-ip.sh [network]
# Default network: home

get-state-version.sh

Gets the default stateVersion from an existing configuration:

files/claude-skills/add-nixos-machine/scripts/get-state-version.sh <machine-name>

Workflow for stateVersion:

Create machine config WITHOUT explicit stateVersion
Run validation to ensure config evaluates
Run get-state-version.sh <machine-name> to get the default value
Add explicit system.stateVersion = "X.Y"; to the config

Key Patterns

inventoryHostName in specialArgs

For machines that use inventory IP allocation, pass inventoryHostName in specialArgs:

flake.nixosConfigurations.machine-name = inputs.nixpkgs.lib.nixosSystem {
  system = "x86_64-linux";
  specialArgs = {
    inventoryHostName = "machine-name";
  };
  modules = [ self.nixosModules.machine-name-configuration ];
};

Machines without inventory IP

For isolated machines, skip the inventory IP allocation but still:

Add hostId to inventory/host-id.nix
Configure networking manually in the module

Per-machine user configuration

To add per-machine home-manager settings:

flake.homeModules.machine-name-binarin = {...}: {
  key = "nixos-config.modules.home.machine-name-binarin";
  # per-machine settings here
};

# In the nixosModule:
home-manager.users.binarin = self.homeModules.machine-name-binarin;

Quick Reference

File locations:

Machine modules: modules/machines/<name>.nix
Host IDs: inventory/host-id.nix
IP allocation: inventory/networks/home.nix
Hardware configs: machines/<name>/hardware-configuration.nix

Validation commands:

Fast: ncf eval nixos
Comprehensive: ncf eval all
Format: nix fmt && just lint

Common module imports:

self.nixosModules.baseline - base configuration
self.nixosModules.baseline - baseline for workstations/servers
self.nixosModules.srvos-bits - server-oriented configuration
self.nixosModules.lxc - LXC container support
self.nixosModules.binarin-workstation - user binarin with full workstation setup
self.nixosModules.binarin-baseline - user binarin with minimal setup
self.nixosModules.tailscale - Tailscale VPN

For complete module templates, see REFERENCE.md.

Agent Skills: Add NixOS Machine

Install this agent skill to your local

Skill Files