nix-config/AGENTS.md

Agent Guide

Directory Structure

/etc/nixos/
├── flake.nix                    # Main flake configuration
├── flake.lock                   # Locked versions
├── AGENTS.md                    # This file
├── treefmt.nix                  # Code formatting config
├── qemu.nix                     # QEMU testing config
│
├── systems/                     # System configurations by architecture
│   ├── aarch64-linux/
│   │   ├── macbook-pro-nixos/   # Apple Silicon MacBook
│   │   │   ├── default.nix
│   │   │   ├── boot.nix
│   │   │   ├── services.nix     # logind, gdm, gnome, flatpak, etc.
│   │   │   ├── filesystems.nix
│   │   │   ├── hardware-configuration.nix
│   │   │   └── firmware/        # Asahi firmware
│   │   └── pi5/                 # Raspberry Pi 5
│   │       ├── default.nix
│   │       ├── boot.nix
│   │       ├── adguard.nix
│   │       └── sops.nix
│   ├── x86_64-linux/
│   │   ├── matt-nixos/          # Desktop AMD system
│   │   │   ├── default.nix
│   │   │   ├── boot.nix
│   │   │   ├── filesystems.nix
│   │   │   ├── sops.nix
│   │   │   └── services/
│   │   │       ├── lsfg-vk/
│   │   │       ├── ratbagd/
│   │   │       └── restic/
│   │   ├── allyx/               # ASUS ROG Ally X
│   │   │   ├── default.nix
│   │   │   └── boot.nix
│   │   ├── nuc-nixos/           # Intel NUC
│   │   ├── jallen-nas/          # NAS server
│   │   └── iso-minimal/
│   └── aarch64-darwin/
│       └── macbook-pro/         # macOS (nix-darwin)
│
├── homes/                       # Home-manager configurations
│   ├── aarch64-linux/
│   │   └── matt@macbook-pro-nixos/
│   │       └── default.nix
│   ├── x86_64-linux/
│   └── aarch64-darwin/
│
├── modules/                     # Shared modules
│   ├── nixos/                   # NixOS system modules
│   ├── home/                    # Home-manager modules
│   └── darwin/                  # nix-darwin modules
│
├── packages/                    # Custom package overlays
│   ├── omnissa/
│   ├── bcachefs/
│   ├── raspberrypi/
│   ├── comfyui/
│   ├── homeassistant/
│   ├── librepods-beta/
│   └── ...
│
└── secrets/                     # SOPS secrets
    ├── secrets.yaml             # Master key config
    └── *-secrets.yaml          # Per-host secrets

System Configurations

macbook-pro-nixos (Apple Silicon MacBook)

• Path: systems/aarch64-linux/macbook-pro-nixos/
• Key files:
  • services.nix:72-81 - logind/sleep settings
  • default.nix - main config, imports all parts
  • boot.nix - systemd-boot, kernel params
• Features: Asahi Linux, GNOME, Hyprland option, battery management

matt-nixos (AMD Desktop)

• Path: systems/x86_64-linux/matt-nixos/
• Features: AMD GPU (LACT), GNOME, gaming, Lanzaboote

allyx (ASUS ROG Ally X)

• Path: systems/x86_64-linux/allyx/
• Features: Jovian NixOS, Steam, handheld-daemon, AMD GPU

pi5 (Raspberry Pi 5)

• Path: systems/aarch64-linux/pi5/
• Features: Headless, AdGuard, Docker, static IP, UEFI boot

jallen-nas (NAS Server)

• Path: systems/x86_64-linux/jallen-nas/
• Features: Headless, VPN, bcachefs, restic backups

NixOS Modules (modules/nixos/)

Desktop Environments

• desktop/gnome/default.nix - GNOME configuration
• desktop/hyprland/default.nix - Hyprland configuration
• desktop/cosmic/default.nix - Cosmic DE configuration

Hardware

• hardware/amd/default.nix - AMD GPU (LACT)
• hardware/nvidia/default.nix - NVIDIA GPU
• hardware/battery/default.nix - Battery management
• hardware/raspberry-pi/ - Raspberry Pi support

Boot & System

• boot/common/ - Common boot settings
• boot/lanzaboote/ - Lanzaboote (secure boot)
• boot/systemd-boot/ - Systemd-boot config
• boot/plymouth/ - Plymouth splash screen

Networking

• network/default.nix - Network configuration (hostname, firewall, NM)
• network/options.nix - Network module options

Other Services

• headless/default.nix - Headless server config (watchdog, no suspend)
• gaming/default.nix - Steam, Gamescope, Gamemode
• programs/default.nix - System programs (nix-index, gnupg, etc.)

Home-Manager Modules (modules/home/)

Programs

• programs/waybar/ - Wayland bar
• programs/hyprland/ - Hyprland config
• programs/kitty/ - Kitty terminal
• programs/wofi/ - Wofi launcher
• programs/wlogout/ - Logout menu
• programs/btop/ - System monitor
• programs/git/ - Git configuration
• programs/zsh/ - Zsh configuration
• programs/mako/ - Notification daemon

Desktop

• desktop/gnome/ - GNOME settings
• desktop/stylix/ - Stylix theming

Services

• services/sops/ - SOPS integration

Custom Packages (packages/)

• omnissa/ - Omnissa Horizon client
• bcachefs/ - Bcachefs tools
• raspberrypi/ - Raspberry Pi firmware/tools
• comfyui/ - ComfyUI packages
• homeassistant/ - Home Assistant components
• librepods-beta/ - LibrePODS beta (AirPods support)

Common Patterns

Enable a desktop environment

${namespace}.desktop.gnome.enable = true;
${namespace}.desktop.hyprland.enable = true;

Enable SOPS

${namespace}.sops.enable = true;

Enable headless mode

${namespace}.headless.enable = true;

System imports

imports = [
  ./boot.nix
  ./filesystems.nix
  ./hardware-configuration.nix
  ./services.nix
];

Namespace options (flake.nix:253)

namespace = "mjallen";

SOPS Secrets

Secrets are encrypted with SOPS. Each system has its own secrets file:

• secrets/mac-secrets.yaml - macbook-pro-nixos
• secrets/pi5-secrets.yaml - pi5
• secrets/allyx-secrets.yaml - allyx
• secrets/nuc-secrets.yaml - nuc-nixos
• secrets/nas-secrets.yaml - jallen-nas

Flake Inputs (flake.nix)

Key inputs:

• nixpkgs-unstable - Unstable channel
• nixpkgs-stable - Stable channel (25.11)
• home-manager-unstable - Home-manager
• nixos-apple-silicon - Apple Silicon support
• nixos-hardware - Common hardware configs
• disko - Disk partitioning
• sops-nix - Secrets management
• lanzaboote - Secure boot
• jovian - Steam Deck support (allyx)

Lib Module (lib/)

Custom utility library exposed via lib.mjallen.* through Snowfall Lib. Used for creating modules and managing versions.

Directory Structure

lib/
├── default.nix          # Entry point: exports module, file, versioning
├── README.md            # Detailed documentation
├── module/              # Module creation helpers
│   └── default.nix
├── file/                # File/path utilities
│   └── default.nix
└── versioning/          # Multi-source version pinning
    └── default.nix

Module Utilities (lib.mjallen.module)

mkModule - Create NixOS service modules with standardized options:

lib.mjallen.module.mkModule {
  config, name, description, options, moduleConfig, domain ? "services"
}

Standard options: enable, port, reverseProxy, firewall, createUser, configureDb, redis, puid, pgid, timeZone, etc.

mkContainerService - For Podman/OCI containers (auto-generates container definition):

lib.mjallen.module.mkContainerService {
  config, name, image, internalPort, description, options, volumes, environment
}

mkSopsEnvFile - Generate SOPS secrets + template env-file:

lib.mjallen.module.mkSopsEnvFile {
  secrets, name, content, restartUnit, owner, group, mode, sopsFile
}

Option Helpers:

• mkOpt type default description - Standard option
• mkBoolOpt default description - Boolean option
• mkReverseProxyOpt name - Caddy reverse proxy sub-options

Convenience Shorthands:

• enabled = { enable = true; }
• disabled = { enable = false; }

Home Manager Utilities

mkHomeModule - Create Home Manager modules:

lib.mjallen.module.mkHomeModule {
  config, domain, name, description, options, moduleConfig
}

File Utilities (lib.mjallen.file)

• readFile path - Read file contents
• pathExists path - Check if path exists
• safeImport path default - Safe Nix import
• getFile relativePath - Get path relative to flake root
• importModulesRecursive path - Recursively discover Nix modules
• scanSystems systemsPath - Discover system configurations
• filterNixOSSystems systems - Filter for Linux systems
• filterDarwinSystems systems - Filter for macOS systems
• scanHomes homesPath - Parse home-manager configurations

Versioning Utilities (lib.mjallen.versioning)

For packages with version.json (multi-variant source pinning):

• selectVariant spec variantName system - Select variant from spec
• render value variables - Template substitution (${var})
• mkSrc pkgs comp variables - Build single source
• mkAllSources pkgs selected - Build all sources for selected variant

See lib/versioning/default.nix for full API and docs/version.schema.json for schema.

Usage in Packages

Create packages/<name>/version.json with variant definitions, then use:

let
  versioning = inputs.self.lib.mjallen.versioning;
  spec = inputs.self.lib.mjallen.file.readFile ./version.json;
  selected = versioning.selectVariant spec variantName system;
  sources = versioning.mkAllSources pkgs selected;
in
# Use sources.componentName for each source