AGENTS.md - NixOS Flake Configuration

Before Starting Work

Run hostname to identify current machine. Hostname = flake config name (e.g., frame12 → .#frame12).

Repository Structure

flake.nix           # Defines all nixosConfigurations
<hostname>/         # Per-host configs (frame12, nate, jaci, scrappy, nate-work, luci)
  default.nix       # Host entry point, sets deskCfg or serverConfig
  desktop-configuration.nix  # Desktop systems only
  modules/          # Host-specific modules (niri, home-manager, user)
  nixos/hardware-configuration.nix  # Auto-generated, do not edit
shared/             # Reusable modules imported by hosts
  modules/          # apps/, home-manager/, services/, system/, user/
  server-configuration.nix  # Server base (luci uses this)

Host types:

Desktop (frame12, nate, jaci, nate-work, scrappy): Use deskCfg options, Home Manager, Stylix theming
Server (luci): Uses serverConfig options, minimal packages

Build/Test Commands

nix flake check                    # Validate syntax
nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel --dry-run
# Must be done by user, agent lacks admin privileges.
sudo nixos-rebuild test --flake .#<hostname>  # Test without switching
sudo nixos-rebuild switch --flake .#<hostname>  # Apply changes

Key Patterns

Configuration options: Desktops set deskCfg = { userName, hostName, de }, servers set serverConfig = { userName, hostName, hostId, ... }

Module structure: Options in options.<name>, config in config = lib.mkIf cfg.enable { ... }

Home Manager: User config in <host>/modules/home-manager/home.nix, packages in home.packages

Shared imports: ../shared/modules/<path> for reusable modules

Code Style

Nix expression language, 2-4 space indent
camelCase options (userName), kebab-case hostnames, underscores for modules (main_user)
lib.mkOption with types (lib.types.str, lib.types.bool), lib.mkEnableOption for toggles
lib.mkIf for conditionals, lib.mkMerge for combining sets
Minimal comments; use self-documenting option descriptions

2.1 KiB Raw Blame History