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)