nixos-config

NixOS Configuration Skill

Announce at start: "I'm using the nixos-config skill to work with your Nix configuration."

Critical Reminders

• Flakes only — never use channels or nix-env
• Declarative always — never use imperative approaches when declarative solutions exist
• jj new before building — new files must be tracked; run jj new so they appear in git HEAD
• Always build-test — never consider the task complete without a successful build
• Clean up result symlinks — remove any result symlinks created during builds

Quick Reference

Task	Command
Rebuild NixOS (test)	sudo nixos-rebuild test --flake .#<hostname>
Rebuild NixOS (switch)	sudo nixos-rebuild switch --flake .#<hostname>
Home Manager build	home-manager build --flake .#user@hostname --no-out-link
Home Manager switch	home-manager switch --flake .#user@hostname
Check flake	nix flake check
Evaluate expression	nix-instantiate --eval -E '<expr>'
Interactive REPL	nix repl
Show derivation	nix show-derivation
Update single input	nix flake update <input>
Update all inputs	nix flake update

Workflow

Phase 1: Analyze Existing Configuration

Before making changes, understand the current setup:

1. Read flake.nix to understand inputs, outputs, and structure
2. Identify the module organization pattern (flat vs nested, custom namespaces like mynix)
3. Check for existing conventions:
   • Option naming patterns
   • Module enable/disable patterns
   • Import structure
   • Custom library functions
4. Note the hostname(s) and user(s) configured

Phase 2: Plan Changes

Determine scope and approach:

1. NixOS vs Home Manager — system-level services and kernel config go in NixOS modules; user programs, dotfiles, and user services go in Home Manager
2. New module vs existing — prefer extending existing modules unless the feature is clearly separate
3. Option design — plan option names, types, and defaults that match existing conventions
4. Explain the planned changes to the user before implementing

Phase 3: Implement

Write the configuration following Nix best practices:

• Use lib.mkEnableOption for boolean toggles
• Use lib.mkOption with proper types (types.str, types.listOf, types.attrsOf, etc.)
• Use lib.mkIf for conditional configuration
• Use lib.mkDefault for defaults that users can override
• Use lib.mkForce sparingly and only when necessary
• Use lib.mkMerge to combine multiple config blocks
• Use lib.assertMsg for meaningful error messages on invalid config
• Respect the project's existing conventions and namespaces
• Add description strings to custom options

Phase 4: Validate and Build

1. If new files were created, run jj new so they are tracked
2. Build and test:
   • NixOS: sudo nixos-rebuild test --flake .#<hostname>
   • Home Manager: home-manager build --flake .#user@hostname --no-out-link
3. Run nix flake check if structural changes were made to the flake
4. Clean up any result symlinks: rm -f result
5. Squash related changes if needed: jj squash

Phase 5: Troubleshoot If Build Fails

If the build fails, follow this process:

1. Parse the error message — identify the failing module, option, or derivation
2. Use debugging tools:
   • nix-instantiate --eval to test expressions in isolation
   • nix repl to interactively explore values
   • nix show-derivation to inspect build dependencies
3. Fix the issue and rebuild
4. Repeat until the build succeeds

Error Handling

Common Failure Patterns

Error	Cause	Fix
error: getting status of '/nix/store/.../<file>'	New file not tracked by git	Run jj new to snapshot, then rebuild
error: attribute 'X' missing	Typo in option name or missing import	Check spelling, verify module is imported in flake.nix
error: infinite recursion encountered	Circular dependency between options	Break the cycle with lib.mkMerge or restructure
error: value is a X while a Y was expected	Wrong option type	Check mkOption type declaration matches usage
error: option 'X' does not exist	Module not imported or option path wrong	Verify import chain and option path
collision between '/nix/store/...'	Two packages provide same file	Use lib.mkForce or packageOverrides to resolve
error: flake 'X' does not provide attribute	Wrong output path in flake	Check nixosConfigurations / homeConfigurations names

Build Fails After Adding New Files

This is the most common issue. New files are not visible to the Nix evaluator until they are tracked:

jj new          # snapshot new files into git HEAD
# then rebuild

Remember to squash related changes afterward if needed.

Key Principles

1. Declarative — every configuration choice should be expressed declaratively in Nix
2. Minimal changes — make targeted changes that integrate with existing patterns
3. Validate before done — never claim completion without a passing build
4. Respect conventions — follow the project's established module structure, naming, and namespaces
5. Explain changes — describe what was changed and why, highlight breaking changes or migration needs

Resources

Reference materials are available in the references/ directory:

• nix-language.md — Nix language syntax and builtins
• flake-patterns.md — Flake structure, inputs, and overlays
• nixos-modules.md — Module structure, option declarations, and config patterns
• home-manager.md — Home Manager modules, programs, and services
• troubleshooting.md — Error catalog, debugging workflow, and migration patterns