From e2d7fbcae28eae6079549580b4dfb176fd61350c Mon Sep 17 00:00:00 2001 From: DerGrumpf Date: Sat, 18 Apr 2026 10:23:09 +0200 Subject: [PATCH] Updatet README.md; Added AGENTS.md --- AGENTS.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 95 ++++++++++++++++++++++++++++++++++---------- 2 files changed, 190 insertions(+), 22 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f763f78 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,117 @@ +# 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 # managed via nixvim, runs nixfmt + +# Enter dev shell if defined +nix develop +``` + +## Repo Layout + +``` +flake.nix # Entry point — defines all hosts via mkSystem +hosts// # 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..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//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/.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` diff --git a/README.md b/README.md index d50263d..770001f 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,41 @@ # DerGrumpfs Nix Configuration -A unified Nix configuration for both NixOS and macOS using flakes, nix-darwin, and Home Manager. - -## About - -A single repository managing both machines declaratively with Nix. Shared home-manager configuration across platforms with platform-specific modules where needed. +A unified Nix flake managing NixOS desktops, a macOS machine via nix-darwin, and a home server cluster — all sharing a common Home Manager configuration. **Author:** Phil Keier +--- + ## Machines -| Hostname | Platform | Architecture | -|----------|----------|--------------| -| cyper-desktop | NixOS | x86_64-linux | -| cyper-mac | macOS | x86_64-darwin | +| Hostname | Platform | Architecture | Type | +|---|---|---|---| +| cyper-desktop | NixOS | x86_64-linux | Desktop workstation | +| cyper-mac | macOS | x86_64-darwin | nix-darwin + Homebrew | +| cyper-controller | NixOS | x86_64-linux | Home server (runs all services) | +| cyper-node-1 | NixOS | x86_64-linux | Server node | +| cyper-node-2 | NixOS | x86_64-linux | Server node | + +--- ## Prerequisites ### NixOS + Nix is available out of the box. Enable flakes in your configuration. ### macOS + Install Nix using the [Determinate Systems installer](https://docs.determinate.systems/#products). -**Note:** Homebrew is managed declaratively via nix-homebrew — if already installed it will auto-migrate, otherwise it is installed automatically. +> **Note:** Homebrew is managed declaratively via nix-homebrew — if already installed it will auto-migrate, otherwise it is installed automatically. + +--- ## Quick Start ### Clone + ```bash git clone https://github.com/DerGrumpf/nix ~/.config/nix cd ~/.config/nix @@ -39,7 +47,10 @@ Replace placeholders in `home/git.nix`: - `DerGrumpf` → your Git username - `phil.keier@hotmail.com` → your Git email +Update `secrets/keys.txt.age` and `.sops.yaml` with your age public key. + ### Apply + ```bash # NixOS sudo nixos-rebuild switch --flake .#cyper-desktop @@ -47,43 +58,83 @@ sudo nixos-rebuild switch --flake .#cyper-desktop # macOS darwin-rebuild switch --flake .#cyper-mac -# Or after initial setup on either machine +# Or use the shell alias (auto-detects hostname and platform) nix-switch ``` +### Check (without building) + +```bash +nix-check +# expands to: nix flake check --no-build (NixOS) +# or: nix eval ...darwinConfigurations.(hostname).config... (macOS) +``` + +--- + ## Project Structure + ```mermaid graph TD flake[flake.nix] --> desktop[nixosConfigurations
cyper-desktop] + flake --> servers[nixosConfigurations
cyper-controller / node-1 / node-2] flake --> mac[darwinConfigurations
cyper-mac] desktop --> nixos[nixos/
NixOS system modules] - desktop --> hd[hosts/cyper-desktop/
hardware + networking] - desktop --> home[home/
shared home-manager] + desktop --> hd[hosts/cyper-desktop/
hardware + config] + desktop --> home[home/
shared Home Manager] + + servers --> nixos + servers --> roles[nixos/roles/
Gitea · Matrix · Vaultwarden
AdGuard · Searxng · Unifi
Monitoring · Filebrowser] + servers --> hc[hosts/cyper-*/] mac --> darwin[darwin/
macOS system modules] - mac --> hm[hosts/cyper-mac/
host specific] + mac --> hm[hosts/cyper-mac/] mac --> home - home --> shared[shared
packages, git, shell, python
nixvim, nixcord, spicetify
floorp, obsidian] + home --> shared[shared
packages · git · shell · python
nixvim · nixcord · spicetify
floorp · obsidian · ssh] home --> deskmod[desktop/] - - deskmod --> dlinux[Linux only
hyprland, niri
waybar, rofi
gtk, qt, onlyoffice
xdg, waypaper] + deskmod --> dlinux[Linux only
hyprland · niri · waybar
rofi · gtk · qt · xdg · waypaper] deskmod --> dmac[macOS only
sketchybar] ``` +--- + ## Secrets -Secrets are managed with [sops-nix](https://github.com/Mic92/sops-nix) and age encryption. The age key must be present at: +Secrets are managed with [sops-nix](https://github.com/Mic92/sops-nix) and age encryption. -- **Linux:** `~/.config/sops/age/keys.txt` -- **macOS:** `~/.config/sops/age/keys.txt` +The age key must exist at `~/.config/sops/age/keys.txt` on every host. To edit secrets: + +```bash +sops secrets/secrets.yaml +``` + +Never edit `.age` files directly. + +--- + +## Shell Aliases (Fish) + +| Alias | Expands to | +|---|---| +| `nix-switch` | `sudo nixos-rebuild switch --flake ~/.config/nix#(hostname -s)` | +| `nix-check` | `nix flake check --no-build` (or darwin eval equivalent) | +| `ls` | `eza --icons=always` | +| `la` | `eza -la --icons=always` | +| `tree` | `eza --icons=always -T` | +| `f` | `nvim $(fzf)` | +| `grep` | `rg` | +| `cp` | `rsync -ah --progress` | +| `l` | LLM prompt via Groq → rendered with `glow` | + +--- ## Useful Links - [Nix manual](https://nixos.org/manual/nix/stable/) -- [nix-darwin docs](https://github.com/LnL7/nix-darwin) +- [nix-darwin](https://github.com/LnL7/nix-darwin) - [Home Manager options](https://nix-community.github.io/home-manager/options.html) - [sops-nix](https://github.com/Mic92/sops-nix) - [nixvim](https://github.com/nix-community/nixvim) - +- [Catppuccin for Nix](https://github.com/catppuccin/nix)