diff --git a/.agents/Agent.md b/.agents/Agent.md deleted file mode 100644 index 191c298..0000000 --- a/.agents/Agent.md +++ /dev/null @@ -1,579 +0,0 @@ -# Agent Context: nixos-setup - -A complete reference for an AI agent to understand, navigate, and modify this -NixOS homelab configuration repository. - -> **⚠️ MANDATORY:** Before doing anything in this repository, read -> [`GUIDELINES.md`](../GUIDELINES.md) in full and follow it. It contains -> non-negotiable hard rules (never run builds, never edit `flake.lock`, etc.) -> and requires you to **present a plan and get user approval before making any -> changes**. - ---- - -## 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` | diff --git a/.agents/Agents.md b/.agents/Agents.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/.agents/Agents.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index e4db270..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,17 +0,0 @@ -# Claude Instructions — nixos-setup - -**MANDATORY FIRST ACTION:** Read [`GUIDELINES.md`](GUIDELINES.md) in full before -doing anything in this repository. It is the single source of truth for agent -behavior here. - -Key non-negotiable rules from that file: - -- **Always present a plan first** and wait for user approval before making any - changes — no matter how small the task. -- **Never run builds or system switches** (`nixos-rebuild`, `nh os`, `skyg os`, - `nix build`, `nix flake check`, etc.) — zero exceptions, even if asked. -- Never edit `flake.lock`, `*.hardware-configuration.nix`, or anything in - `secrets/`. -- Never add `imports = [...]` to host files. -- Never commit or create branches unless explicitly asked. -- Also read [`.agents/Agent.md`](.agents/Agent.md) for full repository context. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file