118 lines
5.1 KiB
Markdown
118 lines
5.1 KiB
Markdown
# AGENTS.md
|
|
|
|
A guide for AI coding agents working in this Nix flake repository.
|
|
|
|
## Project Overview
|
|
|
|
Multi-host Nix flake managing NixOS desktops, macOS via nix-darwin, and a home server cluster — all sharing a common Home Manager configuration. Secrets are encrypted with sops-nix + age.
|
|
|
|
## Key Commands
|
|
|
|
```fish
|
|
# Apply config on current host (works on any machine)
|
|
nix-switch # alias for: sudo nixos-rebuild switch --flake ~/.config/nix#(hostname -s)
|
|
# or: sudo darwin-rebuild switch --flake .#(hostname -s)
|
|
|
|
# Check flake without building (NixOS) / eval toplevel (macOS)
|
|
nix-check
|
|
|
|
# Validate flake inputs and locks
|
|
nix flake check --no-build
|
|
|
|
# Format Nix files
|
|
nixfmt <file> # managed via nixvim, runs nixfmt
|
|
|
|
# Enter dev shell if defined
|
|
nix develop
|
|
```
|
|
|
|
## Repo Layout
|
|
|
|
```
|
|
flake.nix # Entry point — defines all hosts via mkSystem
|
|
hosts/<hostname>/ # Per-host configuration.nix + hardware-configuration.nix
|
|
nixos/ # Shared NixOS system modules (audio, fonts, sops, tailscale…)
|
|
nixos/roles/ # Optional services (Gitea, Matrix, Vaultwarden, AdGuard…)
|
|
darwin/ # macOS-only system modules (fonts, homebrew, yabai, sketchybar)
|
|
home/ # Shared Home Manager config (all hosts, both platforms)
|
|
home/desktop/ # Desktop-only home modules — Linux (hyprland/niri, waybar, rofi…)
|
|
home/desktop/sketchybar/ # macOS-only bar config
|
|
home/neovim/ # nixvim configuration split by plugin
|
|
assets/ # Wallpapers and avatar images — do not modify programmatically
|
|
secrets/ # age-encrypted secrets — never edit .age files directly
|
|
```
|
|
|
|
## Hosts
|
|
|
|
| Hostname | Platform | Type | Notes |
|
|
|---|---|---|---|
|
|
| cyper-desktop | NixOS x86_64 | Desktop | Primary Linux workstation |
|
|
| cyper-mac | macOS x86_64 | Desktop | nix-darwin + Homebrew |
|
|
| cyper-controller | NixOS x86_64 | Server | Runs all roles/services |
|
|
| cyper-node-1 | NixOS x86_64 | Server | `isServer = true` |
|
|
| cyper-node-2 | NixOS x86_64 | Server | `isServer = true` |
|
|
|
|
## mkSystem Convention
|
|
|
|
All hosts are built via `mkSystem` in `flake.nix`. Key flags:
|
|
|
|
- `isDarwin = true` → uses `darwin.lib.darwinSystem` + darwin modules
|
|
- `isServer = true` → skips desktop/GUI modules; both flags are passed as `specialArgs` to all modules via `sharedSpecialArgs`
|
|
|
|
Guard platform-specific code with:
|
|
|
|
```nix
|
|
if isDarwin then { ... } else { ... }
|
|
if isServer then { ... } else { ... }
|
|
```
|
|
|
|
## Home Manager
|
|
|
|
A single `home/` tree is shared by all hosts. Desktop-only modules live under `home/desktop/` and are conditionally included. The `isDarwin` and `isServer` flags are available as `specialArgs` inside Home Manager modules.
|
|
|
|
## Secrets
|
|
|
|
Managed with [sops-nix](https://github.com/Mic92/sops-nix) + age encryption.
|
|
|
|
- **Never edit `.age` files directly** — use `sops secrets/secrets.yaml`
|
|
- Age key must exist at `~/.config/sops/age/keys.txt` on every host
|
|
- Public keys are declared in `secrets/keys.txt.age` and `.sops.yaml` (if present)
|
|
- Secrets are referenced in Nix via `config.sops.secrets.<name>.path`
|
|
|
|
## Conventions
|
|
|
|
- **Formatter:** `nixfmt` (run via nixvim; apply before committing)
|
|
- **No `hardware-configuration.nix` edits** — these are machine-generated; regenerate with `nixos-generate-config` if needed
|
|
- **Homebrew** is managed declaratively via `darwin/homebrew.nix` — do not run `brew install` manually
|
|
- **Catppuccin** theming is applied system-wide via `home/catppuccin.nix` and `nixos/catppuccin.nix`; keep theme tokens consistent across modules
|
|
- **Shell is Fish** — shell aliases and functions live in `home/shell.nix`; use fish syntax
|
|
|
|
## Adding a New Host
|
|
|
|
1. Create `hosts/<hostname>/configuration.nix` (and `hardware-configuration.nix` for NixOS)
|
|
2. Add an entry to `nixosConfigurations` (or `darwinConfigurations`) in `flake.nix` via `mkSystem`
|
|
3. Add the host to the machines table in `README.md` and this file
|
|
|
|
## Adding a New Role/Service
|
|
|
|
1. Create `nixos/roles/<service>.nix`
|
|
2. Import it in the relevant host's `configuration.nix` or in `nixos/default.nix` behind an `isServer` guard
|
|
3. Add any required secrets to `secrets/secrets.yaml` via `sops`
|
|
|
|
## PR Checklist
|
|
|
|
- [ ] `nix flake check --no-build` passes
|
|
- [ ] `nixfmt` applied to changed `.nix` files
|
|
- [ ] No hardcoded paths or usernames — use `primaryUser` / `hostName` from `specialArgs`
|
|
- [ ] Secrets referenced via sops, not inlined
|
|
- [ ] `hardware-configuration.nix` untouched unless intentional
|
|
- [ ] README and AGENTS.md updated if hosts, roles, or structure changed
|
|
|
|
## Gotchas
|
|
|
|
- `primaryUser` is defined in `flake.nix` and injected everywhere via `sharedSpecialArgs` — never hardcode the username
|
|
- `home-manager.backupFileExtension = "backup"` is set globally; conflicts create `.backup` files rather than erroring
|
|
- The `l` fish function calls a Groq LLM (`llama-3.3-70b-versatile`) and pipes output through `glow` — it requires `$GROQ_API_KEY` to be set as a file path
|
|
- sketchybar lives under `home/desktop/sketchybar/` but is macOS-only; hyprland/niri are Linux-only
|
|
- `nix-switch` uses `hostname -s` at runtime — the hostname must match a key in `nixosConfigurations` / `darwinConfigurations`
|