Configuring NixOS Systems with Flakes

Configure NixOS systems with flakes, manage overlays properly, and structure configurations for maintainability.

⚠️ CRITICAL: Read Before Making Changes

BEFORE making ANY NixOS configuration changes, you MUST:

1. Review relevant rule files from the Quick Reference below
2. Check common-mistakes.md to avoid known pitfalls
3. Check troubleshooting.md for systematic debugging approach
4. Follow existing patterns in the codebase

Do NOT start coding until you've read the applicable documentation.

Most configuration errors happen from not reading the rules first. The 5 minutes you spend reading will save hours of debugging.

Red Flags - STOP BEFORE CODING

• "I can just try this option" → Check if it exists in nixpkgs/Home Manager first
• "Let me experiment with different approaches" → Read the docs, don't guess
• "This should work" → Verify syntax and availability in nixpkgs
• Making multiple rebuild attempts → You're missing systematic debugging
• "I remember this works" → Docs change, verify current approach

Core Principle

Understand the interaction between NixOS system configuration and Home Manager overlays.

When useGlobalPkgs = true, overlays must be defined at the NixOS configuration level, not in Home Manager configuration files.

When to Use

• Configuring NixOS with flakes and Home Manager
• Adding overlays that don't seem to apply
• Using useGlobalPkgs = true with custom overlays
• Structuring NixOS configurations across multiple hosts
• Package changes not appearing after rebuild
• Confused about where to define overlays

Don't use for:

• Packaging new software (use nix-packaging-best-practices)
• Simple package installation without overlays
• NixOS module development (see NixOS module documentation)

Quick Reference

Essential Pattern: Overlay with useGlobalPkgs

# ❌ WRONG: Overlay in home.nix (doesn't apply)
# home-manager/home.nix
{
  nixpkgs.overlays = [ inputs.claude-code.overlays.default ];  # Ignored!
  home.packages = with pkgs; [ claude-code ];  # Not found!
}

# ✅ CORRECT: Overlay in NixOS home-manager block
# hosts/home/default.nix
{
  home-manager.useGlobalPkgs = true;
  home-manager.useUserPackages = true;
  home-manager.users.chumeng = import ./home.nix;
  home-manager.extraSpecialArgs = { inherit inputs pkgs-stable system; };
  # Overlay must be HERE when useGlobalPkgs = true
  nixpkgs.overlays = [ inputs.claude-code.overlays.default ];
}

Common Tasks

Overlay Scope Decision Matrix

Configuration Layers (Bottom to Top)

1. System configuration (/etc/nixos/configuration.nix or host files)

   • System-wide services
   • System packages
   • System overlays only affect this layer

2. Home Manager (useGlobalPkgs=true)

   • Uses system pkgs (includes system overlays)
   • Home Manager overlays affect both system and user packages
   • Most efficient for single-user systems

3. Home Manager (useGlobalPkgs=false)

   • Creates separate pkgs instance
   • Home Manager overlays affect user packages only
   • Useful for multi-user systems with different needs

Red Flags - STOP

• "Overlay in home.nix isn't working" → Check if useGlobalPkgs=true, move to host config
• "I'll just add overlays everywhere" → Define once at appropriate scope
• "Package works in nix repl but not installed" → Check overlay scope
• "Changes don't apply after rebuild" → Verify overlay is in correct location
• "useGlobalPkgs=false for no reason" → Use true unless you need separate package sets

How to Use

Read individual rule files for detailed explanations and code examples:

rules/overlay-scope.md       # The core overlay scope issue
rules/flakes-structure.md    # How to organize flake.nix
rules/host-organization.md   # How to structure host configs
rules/common-mistakes.md     # Pitfalls and how to avoid them

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md