DerGrumpf/cyper-nix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updatet README.md; Added AGENTS.md

Browse Source
This commit is contained in:
DerGrumpf
2026-04-18 10:23:09 +02:00
parent c251dffab8
commit e2d7fbcae2
2 changed files with 190 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
AGENTS.md Normal file
View File

@@ -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 <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`

95
README.md
View File

@@ -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<br/>cyper-desktop]
flake --> servers[nixosConfigurations<br/>cyper-controller / node-1 / node-2]
flake --> mac[darwinConfigurations<br/>cyper-mac]
desktop --> nixos[nixos/<br/>NixOS system modules]
desktop --> hd[hosts/cyper-desktop/<br/>hardware + networking]
desktop --> home[home/<br/>shared home-manager]
desktop --> hd[hosts/cyper-desktop/<br/>hardware + config]
desktop --> home[home/<br/>shared Home Manager]
servers --> nixos
servers --> roles[nixos/roles/<br/>Gitea · Matrix · Vaultwarden<br/>AdGuard · Searxng · Unifi<br/>Monitoring · Filebrowser]
servers --> hc[hosts/cyper-*/]
mac --> darwin[darwin/<br/>macOS system modules]
mac --> hm[hosts/cyper-mac/<br/>host specific]
mac --> hm[hosts/cyper-mac/]
mac --> home
home --> shared[shared<br/>packages, git, shell, python<br/>nixvim, nixcord, spicetify<br/>floorp, obsidian]
home --> shared[shared<br/>packages · git · shell · python<br/>nixvim · nixcord · spicetify<br/>floorp · obsidian · ssh]
home --> deskmod[desktop/]
deskmod --> dlinux[Linux only<br/>hyprland, niri<br/>waybar, rofi<br/>gtk, qt, onlyoffice<br/>xdg, waypaper]
deskmod --> dlinux[Linux only<br/>hyprland · niri · waybar<br/>rofi · gtk · qt · xdg · waypaper]
deskmod --> dmac[macOS only<br/>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)