93 lines
5.6 KiB
Markdown
93 lines
5.6 KiB
Markdown
# 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](./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](./modules/services/immich.nix)
|
|
|
|
### Secrets
|
|
- Secrets are managed via [SOPS + age](./docs/sops-secrets.md) 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](./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](./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](./README.md) — Full architecture, host roles, and entry point for all docs
|
|
- [docs/software-inventory.md](./docs/software-inventory.md) — Cross-reference matrix of software per host
|
|
- [docs/installation.md](./docs/installation.md) — nixos-anywhere deployment guide
|
|
- [docs/sops-secrets.md](./docs/sops-secrets.md) — SOPS/age secrets management
|
|
- [docs/borg-backup-setup.md](./docs/borg-backup-setup.md) — BorgBackup server setup (deprecated - migrated to Backrest)
|
|
- [docs/homepage-dashboard.md](./docs/homepage-dashboard.md) — Homepage dashboard: adding machines, tabs & services
|