# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Repo Is

A NixOS flake configuration managing multiple hosts (desktops, laptops, servers). All hosts share common settings via `hosts/configuration_common.nix` and are assembled in `hosts/default.nix`.

## Common Commands

```bash
# Format all nix files
nix fmt

# Build a host configuration (no activation)
nixos-rebuild build --flake .#<host>

# Switch the current host
sudo nixos-rebuild switch --flake .#<host>

# Build a custom package
nix build .#<package>

# Edit an age-encrypted secret
agenix -e secrets/<path>.age

# Re-key all secrets after adding a new host key to secrets/secrets.nix
agenix -r
```

## Architecture

### Entry Points

- `flake.nix` — defines inputs (nixpkgs stable=25.11, unstable, home-manager, agenix, lanzaboote, jovian-nixos, microvm, impermanence, noctalia) and calls `hosts/default.nix` for `nixosConfigurations`
- `hosts/default.nix` — instantiates every host via `lib.nixosSystem`; contains the `mkHM` helper that wires home-manager into a host's modules list

### Host Structure

Each host lives in `hosts/<name>/`:
- `default.nix` — imports either `../../modules/desktop` or `../../modules/server`, sets the module options (`myDesktop.*` / `myServer.*`), and adds host-specific settings
- `home.nix` — host-specific home-manager config (merged with `hosts/home.nix` for desktops or `hosts/home_server.nix` for servers)
- `hardware-configuration.nix` — generated hardware config

Shared host-level files:
- `hosts/configuration_common.nix` — applied to every host: SSH (key-only, no root), locale, nix GC/settings, zsh, fonts, auto-upgrade flake URL
- `hosts/home.nix` — desktop home-manager base
- `hosts/home_server.nix` — server home-manager base

### Module System

Two top-level NixOS modules expose all major knobs as typed options:

**`modules/desktop/default.nix`** — `myDesktop.*`
- `windowManager`: `"niri"` (default) | `"sway"` | `"kde"`
- `cpu`: `"amd"` | `"intel"` | `"none"` — selects KVM kernel params
- `virtualisation.enable` — podman (docker-compat) + qemu/libvirt + virt-manager
- `syncthing.{enable,devices,folders}`
- `openrgb.{enable,motherboard}`
- `laptop.{enable,lidSwitch,hibernateDelaySec}`
- `nitrokey.enable`
- `niri.hotkeyVariant`: `"default"` | `"lifebook"`
- `git.signingKey` — SSH key for commit signing
- `extraSystemPackages`

**`modules/server/default.nix`** — `myServer.*`
- `sshPort` (default 2220)
- `virtualisation.{enable,cpu}` — podman only (no libvirt)
- `fail2ban.enable`
- `autoUpgrade.enable` (default true)
- `uid`, `sudoRequiresPassword`, `extraGroups`, `extraSystemPackages`

Service bundles are imported as lists in host `default.nix`:
- `modules/services/server/` — kabtop services (gitea, nextcloud, matrix, coturn, hydra, mealie, etc.)
- `modules/services/nas/` — jupiter services (nfs, vaultwarden, syncthing, paperless)
- `modules/services/dmz/` — dmz services (gitea runner microVM)
- `modules/services/kabtopci/` — kabtopci services (hydra, gitea runner)
- `modules/services/nasbackup/` — nasbak backup jobs

### Secrets (agenix)

`secrets/secrets.nix` declares which age public keys (users + host SSH keys) can decrypt each `.age` file. Add a new host: add its `ssh-ed25519` host key to `secrets/secrets.nix` in the relevant groups, then run `agenix -r` to re-key.

### Custom Packages & Overlays

- `packages/` — custom packages (e.g. `corosync-qdevice`), imported at `flake.nix` level
- `overlays/` — nixpkgs overlays applied globally
- Per-host overlays: set `nixpkgs.overlays` inside the host's `default.nix` so only that host is affected

### Disk Layouts

`disko/` contains reusable disko modules: `btrfs.nix`, `btrfs_luks.nix`, `nas_luks.nix` — referenced during initial install.

## Active Hosts

| Host | Role | WM / Notes |
|---|---|---|
| hades | Desktop | niri, AMD, Secure Boot (lanzaboote) |
| lifebook | Laptop | niri, Intel, Secure Boot |
| steamdeck | Gaming | KDE/Jovian-NixOS, Secure Boot |
| kabtop | Main server | gitea, nextcloud, matrix+bridges, coturn, hydra, mealie |
| kabtopci | CI server | hydra, nix-serve |
| jupiter | NAS | nfs, vaultwarden, syncthing, paperless |
| dmz | DMZ | gitea Actions homerunner microVM |
| nasbak | NAS backup | — |
| kubemaster-1 | K8s master | — |

See `SERVICES.md` for port-level service details per host.