Nix-Vibe/AGENTS.md

AGENTS.md — Nix-Vibe AI Agent Instructions

A Nix Flakes-based multi-host NixOS + Home Manager configuration repository.

Quick Reference

• Build/Test: nix flake check (must git add new files first)
• Task runner: just (see justfile) — just deploys a host + restarts quickshell, just check, just dry-build, just test, just restart-qs
• Format: nixpkgs-fmt . (or nix fmt — the flake defines a nixpkgs-fmt formatter)
• Dev shell: nix develop (provides sops, age, nixpkgs-fmt)
• Apply: sudo nixos-rebuild switch --flake .#<hostname>
• Test (no activation): sudo nixos-rebuild test --flake .#<hostname>
• Remote apply: nixos-rebuild switch --target-host <host> --flake .#<hostname> --use-remote-sudo
• Dry-build: nixos-rebuild dry-build --flake .#<hostname>

Architecture

Directory	Purpose
hosts/<name>/	Per-machine configs (configuration.nix, disko-config.nix, hardware-configuration.nix)
modules/core/	Shared NixOS modules (common, fonts, settings, sops, podman, dev, users, management, known-hosts)
modules/desktop/	GUI desktop modules and app-specific modules
modules/hardware/	Hardware-specific modules (fingerprint, nvidia)
modules/services/	Service modules (immich, jellyfin, ntfy, paperless, immich-proxy)
modules/storage/	Disk configuration via Disko
home-manager/modules/	Shared Home Manager modules (zsh, gnome, firefox, kitty, etc.)
home-manager/users/	Per-user Home Manager configs
flake.nix	Entry point — defines nixosConfigurations via mkNixosSystem helper

Host overview and software inventory: see README.md.

Critical Rules

Style

• Language: Nix — follow conventions used in the nixpkgs repository.
• Formatter: nixpkgs-fmt . (run before every commit).

Git & Flakes

• NEW FILES MUST BE STAGED (git add) before nix flake check or nixos-rebuild. Flake evaluation only sees Git-tracked files.
• Do NOT commit until nix flake check AND a dry-build pass.

Module Pattern

• New service modules follow the pattern: lib.mkEnableOption for enable + lib.mkIf config.services.<name>.enable { ... }.
• Example: modules/services/immich.nix

Secrets

• Secrets are managed via SOPS + age in secrets.yaml.
• Reference in host configs as sops.secrets."<path>" = { ... };.
• Rendered config files (e.g. container env files) use sops.templates — see docs/sops-secrets.md.

Sudo

• Passwordless sudo is granted to petere only via security.sudo.extraRules (NOPASSWD) in modules/core/common.nix. All other wheel users must enter a password for sudo.

Zsh

• programs.zsh.enable = true must be set in NixOS config for Zsh users.
• Shared Zsh config uses home-manager.sharedModules in flake.nix — do NOT use home.file.".zshrc".

Servers vs Desktops

• Servers (richmond-server, homeserver-1, mcf-server) use serverOverlays (lightweight).
• Desktops/laptops use desktopOverlays (stable without CUDA) by default.
• Only x1carbon uses the full overlays set with CUDA, NDI, stable packages (OBS Studio).

Deprecated Options

• Pay attention to warnings about deprecated options during nix flake check or nixos-rebuild. Refer to NixOS/Home Manager release notes for updated options. Keeping configurations current prevents surprises on channel updates.

Homepage Dashboard (gethomepage.dev)

• Dashboard definition for homeserver-1 lives in hosts/homeserver-1/homepage.nix (imported by the host config), NOT in configuration.nix.
• Full guide for adding machines/tabs/services: docs/homepage-dashboard.md.
• Widget group names MUST be unique — the credentialed proxy resolves config by leaf group name; duplicate names cause one machine's stats to render on another's tiles.
• Every Glances widget tile needs a metric field (info, cpu, memory, fs:/, process, ...) and version = 4; omitting metric throws t.metric is undefined.
• Tailscale widget deviceid must be the numeric device ID (from the Tailscale API), not the ...CNTRL value.
• API keys are injected as HOMEPAGE_VAR_* env vars from the SOPS secret homeserver-1/homepage-env — never hardcode keys in homepage.nix.
• After editing homepage.nix, if changes don't appear after rebuild, restart the service: sudo systemctl restart homepage-dashboard (config files are only read at service start).
• Homepage is exposed on Tailscale only (port 8082).

Post-Modification Workflow

1. Update README.md software inventory and host overview if relevant
2. When adding a new host, add it to the Host Reference table in .github/skills/nix-flake-rebuild/SKILL.md (informational; the dry-build loop is dynamic)
3. git add all modified/new files
4. nix flake check
5. nixos-rebuild dry-build --flake .#<hostname> for affected hosts
6. Commit only after both checks pass

Documentation

• README.md — Full architecture, host roles, and entry point for all docs
• docs/software-inventory.md — Cross-reference matrix of software per host
• docs/installation.md — nixos-anywhere deployment guide
• docs/sops-secrets.md — SOPS/age secrets management
• docs/borg-backup-setup.md — BorgBackup server setup (deprecated - migrated to Backrest)
• docs/homepage-dashboard.md — Homepage dashboard: adding machines, tabs & services