diff --git a/.agents/Agent.md b/.agents/Agent.md new file mode 100644 index 0000000..95e41c2 --- /dev/null +++ b/.agents/Agent.md @@ -0,0 +1,573 @@ +# Agent Context: nixos-setup + +A complete reference for an AI agent to understand, navigate, and modify this +NixOS homelab configuration repository. + +--- + +## Repository Purpose + +A **NixOS flake** managing multiple machines (laptops, desktops, servers) and one OpenWrt +router for a personal homelab. Everything is declarative Nix. No imperative scripts except +the `skyg` CLI wrapper and the OpenWrt deploy script. + +The configured user, default system architecture, and NixOS state version are all defined +in `flake.nix` (the `lib =` binding at the top of `outputs`). Check that file for +source-of-truth values rather than relying on any hardcoded constants here. + +--- + +## Repository Layout + +``` +nixos-setup/ +├── flake.nix # All outputs: nixosConfigurations, homeConfigurations, packages, devShells +├── flake.lock # Locked input revisions — do not edit by hand +├── secrets.nix # agenix: maps .age files → authorized SSH public keys +├── bin/ +│ ├── skyg # Bash shim: exec nu --commands "use lib/cmds.nu *; skyg $*" +│ └── lib/ +│ ├── cmds.nu # All skyg subcommands (NuShell — source of truth) +│ ├── profile.nu # Profile helpers and tab-completion data +│ └── types.nu # Type definitions +├── hosts/ +│ ├── .nix # One file per managed machine +│ ├── .hardware-configuration.nix +│ ├── iso.nix # Bootable install image +│ └── scripts/ # Host-specific helper scripts +├── modules/ +│ ├── lib.nix # makeNixOs / makeIso / makeHomeManagerUsers / makeDarwinModule / eachSystem +│ ├── main.nix # Base module every host gets: core/ + nixos/ + network-drives.nix +│ ├── skyg-utils.nix # makeHyperlinkScriptToConfigs (symlinks configs/ → ~/.config/) +│ ├── macos.nix # macOS/nix-darwin module +│ ├── network-drives.nix # skyg.networkDrives — NFS auto-mounts +│ ├── core/ +│ │ ├── default.nix # Imports: user.nix, macos.nix, nix-substituters.nix +│ │ ├── user.nix # skyg.user.* and skyg.home-manager.* options; wires HM +│ │ ├── nix-substituters.nix # Binary caches + remote builder config +│ │ └── macos.nix # Pipx workaround overlay; distributed build config +│ ├── home/ +│ │ ├── default.nix # makeCommonUser / makeRootUser factories +│ │ ├── programs.nix # bat, neovim, direnv, eza, starship, nushell, carapace, zsh, zellij, tmux +│ │ ├── services.nix # gpg-agent with SSH support +│ │ ├── fonts.nix # Font packages +│ │ └── git.nix # makeCommonGitConfigs +│ ├── nixos/ +│ │ ├── default.nix # Imports: common/ + server/ + desktop/ +│ │ ├── common/ +│ │ │ ├── core.nix # nix-ld, nh, appimage-run, GC cron, timezone, locale +│ │ │ ├── networking.nix # skyg.core.hostName; NetworkManager; disables nm-wait-online +│ │ │ ├── user.nix # System user creation; zsh as default shell +│ │ │ ├── ssh-server.nix # skyg.nixos.common.ssh-server.enable; key-only SSH +│ │ │ ├── qemu.nix # skyg.core.qemu.enable; QEMU + SPICE stack +│ │ │ ├── fonts.nix +│ │ │ ├── hardware/ # amdgpu, nvidia, coral-tpu-udev, fan2go, fancontrol, laptop-power, pipewire, sound +│ │ │ ├── containers/ # Docker/Podman options; local registry config; metrics port +│ │ │ └── pritunl/ # Pritunl VPN client +│ │ ├── server/ +│ │ │ ├── admin.nix # skyg.server.admin.enable → www-data group +│ │ │ ├── exporters.nix # skyg.server.exporters.enable → Prometheus node exporter +│ │ │ ├── timers.nix # skyg.server.timers attrset → systemd timer+service pairs +│ │ │ ├── k3s/ # skyg.nixos.server.k3s.{enable,role,envPath} +│ │ │ ├── k8s/ # Raw Kubernetes: master.nix + node.nix +│ │ │ ├── dns/ # certbot/, routing/ (dnsmasq), local-ca/ +│ │ │ ├── arrs/ # Prowlarr + DB for *arr stack +│ │ │ └── services/ # ai-services, audiobookshelf, comfyui, dockge, jellyfin, scrypted +│ │ └── desktop/ +│ │ ├── default.nix # skyg.nixos.desktop.enable; PipeWire, dbus, portals, avahi +│ │ ├── wayland.nix # NIXOS_OZONE_WL=1, xwayland +│ │ ├── tiler/ # DankMaterialShell + niri + hyprland + swww +│ │ ├── stylix/ # skyg.nixos.desktop.stylix.enable +│ │ ├── gnome.nix / kde.nix / cosmic.nix +│ │ ├── crypto.nix # skyg.nixos.desktop.crypto.enable +│ │ ├── packages.nix +│ │ └── printers.nix +│ └── openwrt/ +│ ├── default.nix # Builds openwrt-gen Rust binary; exports deployScript +│ └── generator/ # Rust: stdin JSON → dnsmasq.conf or ethers +├── openwrt-routers/ +│ └── .nix # Per-router config (IP, SSH user, configSecret path) +├── secrets/ +│ └── *.age # Encrypted secrets (see secrets.nix for authorization map) +├── configs/ +│ ├── niri/ # niri compositor config (symlinked to ~/.config/niri) +│ ├── hypr/ # Hyprland config +│ ├── hyprpanel/ # HyprPanel config +│ └── extra.nu # Extra NuShell config +└── docs/ # Documentation (hosts, modules, secrets, DNS, OpenWrt) +``` + +**For the full host list and per-machine details**, see `docs/hosts/README.md`. + +--- + +## skyg CLI Reference + +`skyg` is implemented in `bin/lib/cmds.nu`. All commands `cd` to `$REPO_ROOT` first. +The `bin/skyg` file is a thin bash shim — the NuShell file is the source of truth. + +### System Deployment + +```bash +# Local system (whichever host the repo is checked out on) +skyg os switch +skyg os test +skyg os switch --build-host # offload compilation to a remote builder + +# Remote system +skyg remote switch # deploys to root@. +skyg remote test # test without activating +skyg remote switch --build-host + +# Rollback +skyg rollback # sudo nixos-rebuild switch --rollback + +# Validate flake without building +skyg check # nix flake check --no-build +``` + +`skyg remote` maps `` → NixOS profile `hl-` → SSH target +`root@.`. See `bin/lib/profile.nu` for the full list of valid targets. + +### Home Manager + +```bash +skyg hm switch # apply for the default profile +skyg hm build # build only +skyg hm switch # explicit profile name +``` + +### Flake Updates + +```bash +skyg update # nix flake update (all inputs) + shows flake.lock diff +skyg update # update a single input, e.g. skyg update nixpkgs +``` + +### OpenWrt + +```bash +skyg openwrt # decrypt router secret, pipe to deploy script +skyg openwrt # explicit router name (matches openwrt-routers/.nix) +``` + +Deploy flow: age-decrypts the router's JSON secret → generates `dnsmasq.conf` + `ethers` +via the Rust binary → shows colored diffs → prompts for confirmation × 2 → SSHes to the +router → validates with `dnsmasq --test` → restarts dnsmasq (auto-reverts on failure). + +### ISO + +```bash +skyg build-iso # nix build .#nixosConfigurations.iso.config.system.build.isoImage +``` + +### Secrets + +```bash +skyg secrets # list known secret names +skyg decrypt # decrypt → .tmp/unencrypted- +skyg encrypt [source] # re-encrypt ← .tmp/unencrypted- +skyg compare-secret # diff .tmp/unencrypted- vs the .age file +``` + +### Profiles + +```bash +skyg profiles # list all configured profiles +skyg profiles true # list remote-only profiles (hl-* prefixed) +``` + +--- + +## Flake Outputs + +```nix +nixosConfigurations = { + # One entry per host — names match hosts/.nix + # See flake.nix for the full list and hardware modules used + = lib.makeNixOs { ... }; + iso = lib.makeIso { ... }; +} + +homeConfigurations = { + # Standalone home-manager (non-NixOS use) + # Profile name defined in flake.nix + = lib.makeHomeManagerUsers { ... }; +} + +packages. = { + # One deploy script per router, named openwrt- + openwrt- = (openwrt (import ./openwrt-routers/.nix)).deployScript; +} + +devShells..default # nix develop shell +formatter. # nixpkgs-fmt +``` + +--- + +## `lib.nix` API + +```nix +lib.makeNixOs { + hostName; # required — sets networking.hostName + system ? "x86_64-linux"; + systemStateVersion ? "26.05"; + configuration ? []; # extra modules/files appended after main.nix +} +# Automatically includes: determinate, stylix, home-manager, nix-flatpak, +# agenix, dms (DankMaterialShell), nix-index-database, hermes-agent NixOS modules. + +lib.makeIso { hostName; ... } # same as makeNixOs + installation-cd-minimal.nix + +lib.makeHomeManagerUsers { + modules ? []; + userConfig ? user; # defaults to the user attrset defined in flake.nix + system ? "x86_64-linux"; +} + +lib.makeDarwinModule { + hostName; user; + system ? "x86_64-darwin"; + configuration ? []; +} + +lib.eachSystem (system: ...) # genAttrs over all systems from nix-systems/default +``` + +`specialArgs` injected into every host module: `unstablePkgs`, `skygUtils`, `user`, +`system`, `hyprlauncher`, `dms`, `noctalia`, `nix-index-database`, `hermes-agent`. + +--- + +## `skyg.*` Option Namespace + +All custom NixOS options. Set these in host files (`hosts/.nix`). + +``` +skyg.user + .name string username + .fullName string + .email string + .enable bool enable home-manager config for this user + .createSystemUser bool create the Linux user account (default: true) + .extraGitConfigs list [{path = "..."}] extra git config includes + +skyg.home-manager + .version string HM stateVersion (default: "26.05") + .extraImports list extra HM modules to import + +skyg.core + .hostName string REQUIRED — sets networking.hostName + .qemu.enable bool QEMU + quickemu + SPICE stack + .substituters.urls list extra Nix binary cache URLs + .substituters.keys list extra Nix binary cache trusted public keys + +skyg.nixos.desktop + .enable bool PipeWire, dbus, libinput, avahi, XDG portals, user groups + .tiler.enable bool DankMaterialShell, gnome-keyring, polkit, wayland tools + .tiler.niri.enable bool niri compositor; symlinks configs/niri → ~/.config/niri + .tiler.hyprland.enable bool Hyprland compositor + .stylix.enable bool Stylix theming + .crypto.enable bool crypto/wallet tools + +skyg.nixos.common + .ssh-server.enable bool OpenSSH, key-only auth, a master pubkey pre-authorized + .hardware + .sound.enable bool + .pipewire.enable bool + .amdgpu.enable bool + .nvidia.enable bool + .laptop-power-mgr.* attrset TLP/power management; lid switch config + .udevrules.coraltpu.enable bool + .containers + .runtime string "docker" (default) | "podman" + .openMetricsPort bool opens the container metrics port + +skyg.nixos.server + .k3s + .enable bool + .role string "server" (default) | "agent" + .envPath string path to env file with K3s tokens/config + .services + .ai.enable bool Ollama+openwakeword containers + Wyoming whisper/piper + .audiobookshelf.* attrset {enable, host, port, openFirewall, configDir, metadataDir} + .comfyui.* attrset {enable, mode ("rocm"|"cuda"), port, rocm.dataDir} + .dockge.* attrset {enable, openFirewall, port, volumes.stacks/data.{nfsServer,share}} + .jellyfin.enable bool NFS-backed storage + .scrypted.enable bool + +skyg.server + .admin.enable bool creates www-data group (gid=33) with user as member + .exporters.enable bool Prometheus node exporter + .timers attrset { = {script, OnCalendar, wantedBy}} → systemd timer+service + .dns + .routing.enable bool + .routing.openFirewall bool + .routing.addressesSecretName string agenix secret name for dnsmasq address= lines + .certbot.enable bool + .certbot.email string + .certbot.publicDomains list + +skyg.networkDrives + .enable bool + .tnas1.{enable, host} NAS host (default defined in network-drives.nix) + .terra1.{enable, host} storage server host + .bigBox2.{enable, host} storage server host + .options list NFS mount options (default: x-systemd.automount, auto, nofail, _netdev) +``` + +The NFS mount points provided by `skyg.networkDrives` are defined in `modules/network-drives.nix`. + +--- + +## Hosts + +See `docs/hosts/README.md` for the full per-host reference (hardware, role, services, ports). + +The `flake.nix` `nixosConfigurations` block is the canonical list of managed systems. +Each host's source file is `hosts/.nix` paired with +`hosts/.hardware-configuration.nix`. + +--- + +## Secrets Management + +Uses [agenix](https://github.com/ryantm/agenix). All `.age` files in `secrets/` are +committed to the repo. `secrets.nix` maps each file to the SSH public keys authorized to +decrypt it — check that file for the current authorization matrix and secret list. + +### Using a secret in a module + +```nix +age.secrets.my-secret = { + file = ../../secrets/my-secret.age; +}; + +# Reference the runtime-decrypted path (e.g. /run/agenix/my-secret). +# Never hardcode a path to the .age file itself in service config. +someOption = config.age.secrets.my-secret.path; +``` + +### Managing secrets + +```bash +# Create or edit +agenix -e secrets/my-secret.age + +# After adding a new host key to secrets.nix, re-encrypt everything: +agenix -r -i ~/.ssh/id_ed25519 + +# skyg wrappers +skyg secrets # list known secret names +skyg decrypt # → .tmp/unencrypted- +skyg encrypt # ← .tmp/unencrypted- +skyg compare-secret # diff plaintext vs encrypted +``` + +`.tmp/` is gitignored. Never commit unencrypted secrets. + +### Adding a secret for a new host + +```bash +ssh root@ "cat /etc/ssh/ssh_host_ed25519_key.pub" +# Add the key to secrets.nix, then: +agenix -r -i ~/.ssh/id_ed25519 +``` + +--- + +## Binary Caches + +Configured in `modules/core/nix-substituters.nix` and applied to all hosts. Includes a +local nix-serve instance on the lab network for fast rebuilds, plus several public caches. +See that file for the current URLs and trusted public keys. + +--- + +## Dev Shell + +```bash +nix develop # or: direnv allow (if .envrc is present) +``` + +Provides: `nixpkgs-fmt`, `nixd`, `nh`, `agenix`, `age`, `home-manager`, `rustc`, `cargo`, +`rust-analyzer`, `nushell` + +- Adds `bin/` to `PATH` → `skyg` is available immediately +- Sets `SKYG_LIB` env var for NuShell +- Enforces `nixpkgs-fmt` as a pre-commit hook on all `.nix` files +- Auto-launches NuShell with `cmds.nu` imported when running interactively + +--- + +## Coding Conventions + +- **Formatter**: `nixpkgs-fmt` — enforced by pre-commit. Run before committing. +- **Options**: Use `lib.mkEnableOption` for booleans, `lib.mkOption` with `type` and + `description` for everything else. +- **Conditional config**: `config = lib.mkIf cfg.enable { ... }` pattern throughout. +- **Defaults**: Use `lib.mkDefault` in `main.nix` so host configs can override cleanly. +- **Unfree**: `nixpkgs.config.allowUnfree = true` is set globally — no need to repeat per-host. +- **Secrets**: Never hardcode sensitive values. Use agenix. Reference + `config.age.secrets..path` at runtime. +- **`specialArgs`**: `unstablePkgs`, `skygUtils`, `user`, `system` are always available + in every module — no need to pass them explicitly. +- **Nix features**: `nix-command` and `flakes` experimental features are enabled everywhere. +- **`nh`**: Preferred over raw `nixos-rebuild`. Used by both `skyg os` and `skyg remote`. + +--- + +## Common Patterns + +### Minimal server host + +```nix +# hosts/.nix +{ ... }: { + skyg.user.enable = true; + skyg.nixos.common.ssh-server.enable = true; + skyg.server.exporters.enable = true; + skyg.networkDrives.enable = true; + + boot.loader.systemd-boot.enable = true; + boot.loader.efi.canTouchEfiVariables = true; + services.fwupd.enable = true; +} +``` + +### Declarative systemd timer + +```nix +skyg.server.timers.my-backup = { + OnCalendar = "daily"; + wantedBy = [ "some-mount.mount" ]; + script = '' + set -eu + ${pkgs.rsync}/bin/rsync -av /src /dest + ''; +}; +``` + +### Enable K3s + +```nix +skyg.nixos.server.k3s = { + enable = true; + role = "agent"; + envPath = "/opt/k3s/k3s.env"; # file contains K3S_URL and K3S_TOKEN +}; +``` + +### Use an agenix secret in a service + +```nix +age.secrets.my-api-key.file = ../../secrets/my-api-key.age; + +services.myapp.apiKeyFile = config.age.secrets.my-api-key.path; +``` + +### NFS-backed Dockge + +```nix +skyg.nixos.server.services.dockge = { + enable = true; + openFirewall = true; + volumes.stacks = { nfsServer = ""; share = "/path/to/stacks"; }; + volumes.data = { nfsServer = ""; share = "/path/to/data"; }; +}; +``` + +### Desktop with tiling WM + +```nix +skyg.nixos.desktop = { + enable = true; + tiler.enable = true; + tiler.niri.enable = true; # or hyprland.enable = true + stylix.enable = true; +}; +``` + +--- + +## Adding a New Host — Checklist + +1. **Create host files**: + ``` + hosts/.nix + hosts/.hardware-configuration.nix # from nixos-generate-config + ``` + +2. **Register in `flake.nix`** under `nixosConfigurations`: + ```nix + = lib.makeNixOs { + hostName = ""; + configuration = [ + ./hosts/.nix + ./hosts/.hardware-configuration.nix + ]; + }; + ``` + +3. **Add SSH host key to `secrets.nix`** if the host needs any secrets: + ```bash + ssh root@ "cat /etc/ssh/ssh_host_ed25519_key.pub" + # Add the key to secrets.nix, then re-encrypt: + agenix -r -i ~/.ssh/id_ed25519 + ``` + +4. **Deploy**: + ```bash + skyg remote switch + ``` + +--- + +## Adding a New Service Module — Checklist + +1. Create `modules/nixos/server/services/.nix`: + ```nix + { config, lib, pkgs, ... }: + let cfg = config.skyg.nixos.server.services.; in + { + options.skyg.nixos.server.services. = { + enable = lib.mkEnableOption "Enable "; + # add typed options here + }; + config = lib.mkIf cfg.enable { + # NixOS configuration goes here + }; + } + ``` + +2. Import in `modules/nixos/server/services/default.nix`: + ```nix + imports = [ ... ./.nix ]; + ``` + +3. Enable on relevant hosts: + ```nix + skyg.nixos.server.services..enable = true; + ``` + +--- + +## Key File Locations + +| What | Path | +|------|------| +| Host registrations (canonical list) | `flake.nix` → `nixosConfigurations` | +| Secret authorization map | `secrets.nix` | +| User / global config (name, email, etc.) | `flake.nix` → `lib =` binding | +| Base module every host receives | `modules/main.nix` | +| Home Manager programs | `modules/home/programs.nix` | +| Binary cache configuration | `modules/core/nix-substituters.nix` | +| SSH master public key | `modules/nixos/common/ssh-server.nix` | +| All `skyg` subcommand implementations | `bin/lib/cmds.nu` | +| Valid remote deployment targets | `bin/lib/profile.nu` | +| Router configs | `openwrt-routers/` | +| Desktop compositor configs | `configs/` | +| Full host documentation | `docs/hosts/README.md` | +| Module architecture + option reference | `docs/modules/README.md` | +| Secrets workflow | `docs/secrets/README.md` |