# CLAUDE.md

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

## Repository purpose

Personal NixOS configuration managing multiple hosts via a single flake. Each host is a separate `nixosConfiguration` output in `flake.nix`. Home Manager is wired in as a NixOS module per host. Upstream is `nixos-25.11`.

## Hosts

Defined in `flake.nix` under `nixosConfigurations`:

- `fuji` — x86_64 laptop, intel 13th gen, dual wireguard (one in a network namespace for ProtonVPN routed via `dnscrypt-proxy`). No desktop environment: `plasma6.enable = false`, greetd/tuigreet defaults to sway, river is offered as a second session via a hand-rolled `river-session` package. KDE *applications* (dolphin, okular, ark, kdenlive) are still installed — see the ksycoca note below.
- `nixy` — x86_64 workstation (also builds the `nixy_iso` installer image)
- `mediabox` — x86_64 media server (jellyfin/qbittorrent; uses the local `modules/qbittorrent.nix`)
- `blue` — x86_64 (no sops-nix)
- `magpie` — **aarch64**, qemu guest, runs `simple-nixos-mailserver`; the wireguard hub other hosts dial into

When adding a new host, follow the pattern in `flake.nix`: include `common/packages.nix`, `common/suspend.nix`, the host's `configuration.nix` + `hardware-configuration.nix`, `sops-nix.nixosModules.sops` (if secrets needed), and a home-manager block pointing at `home/<host>/home.nix`.

## Common commands

```sh
# Rebuild the current host (uses hostname to select config)
sudo nixos-rebuild switch --flake .#

# Rebuild a specific host
sudo nixos-rebuild switch --flake .#fuji

# Test without making the new generation the default boot entry
sudo nixos-rebuild test --flake .#fuji

# Build the nixy installer ISO
nix build .#nixosConfigurations.nixy_iso.config.system.build.isoImage

# Update a single flake input
nix flake update nixpkgs

# Format Nix files (formatter is alejandra)
nix fmt

# Enter the dev shell (sops, ssh-to-age, age available)
nix develop

# Cross-build magpie (aarch64) from x86_64 — requires binfmt or remote builder
nix build .#nixosConfigurations.magpie.config.system.build.toplevel
```

`fuji` has `boot.binfmt.emulatedSystems` for wasm32-wasi + x86_64-windows but **not** aarch64, so building magpie locally from fuji needs a remote builder or adding aarch64 to that list.

## Directory layout

- `<host>/configuration.nix` + `<host>/hardware-configuration.nix` — per-host NixOS config
- `<host>/secrets/*.yaml` — sops-encrypted secrets, decrypted at activation via the host's SSH host key (`/etc/ssh/ssh_host_ed25519_key` → age)
- `common/` — modules imported by every host (`packages.nix`, `suspend.nix`) plus shared wireguard pubkeys and `common/secrets/` for cross-host secrets like the wireguard preshared key
- `home/<host>/home.nix` — entry point for that host's home-manager config
- `home/common/` — shared home-manager modules (zsh, sway, i3, i3status-rust, firefox, etc.) imported from per-host `home.nix`
- `modules/` — local NixOS modules not yet upstream-ready (currently `qbittorrent.nix`, `nextcloud.nix`)
- `packages/` — derivations for packages built locally (`bubblewrap`, `viber`)

## Architectural notes worth knowing before editing

**Inputs are passed as `_module.args` to every module.** That means `configuration.nix` files receive `nvim`, `zremap`, `swaysw`, `system`, etc. as function arguments — they aren't imported explicitly. When you see an unfamiliar identifier in a host module's arg list, check `flake.nix` inputs.

**sops-nix wiring.** Secrets decrypt using the host's SSH ed25519 host key converted to age. Each host's `sops.secrets.<name>` references either `./secrets/<file>.yaml` (host-local) or `../common/secrets/<file>.yaml` (shared). `config.sops.secrets.<name>.path` is the runtime decrypted path — pass it to systemd units, never read the file at eval time.

**Fuji's split-tunnel ProtonVPN.** `fuji/configuration.nix` builds a `wg` network namespace, brings up `proton_wg` inside it, and runs `dnscrypt-proxy_proton` bound to that namespace. Anything that should egress over Proton must be launched with `ip netns exec wg ...`. The main-host `wg0` interface is unrelated and connects to magpie for the personal mesh (`10.100.0.0/24`).

**KDE apps outside Plasma need an XDG menu file.** `kbuildsycoca6` indexes only the `.desktop` files reachable from `"$XDG_MENU_PREFIX"applications.menu`; with no such file it builds a ksycoca containing zero applications, and every KIO consumer silently degrades — Dolphin stops honouring default handlers and its "Open With" chooser comes up empty. Plasma used to supply both halves (`XDG_MENU_PREFIX=plasma-` plus `plasma-applications.menu`); sway/river set no prefix, so `fuji/configuration.nix` installs `environment.etc."xdg/menus/applications.menu"` from `plasma-workspace` (already in the closure via the KDE portal backend, so it costs nothing). Note that `mimeapps.list` and `mimeinfo.cache` are *not* involved — `xdg-mime query default` will look correct while Dolphin is broken, so debug this with `strings -el ~/.cache/ksycoca6_* | grep -c '\.desktop'` instead.

**mimeapps.list is read-only.** Home-manager symlinks both `~/.config/mimeapps.list` and `~/.local/share/applications/mimeapps.list` into the store, so "Remember application association" in any chooser fails to persist. Add associations to `xdg.mimeApps` in `home/<host>/home.nix` instead.

**Home-manager backup extension.** `backupFileExtension = "home_backup"` is set on most hosts — if a switch fails on file conflicts, look for `*.home_backup` files in `$HOME`.

**Hardening already in place on fuji** (mirror to other hosts when relevant): nftables firewall, scudo allocator, AppArmor, sysctl hardening (kptr_restrict, dmesg_restrict, rp_filter, redirect blocking), `sudo.execWheelOnly`, `firewall.logRefusedConnections`, doas, firejail, no coredumps, `KillUserProcesses`, ro nix store mount, systemd-boot editor disabled.

## Editing secrets

```sh
nix develop          # gets sops + age + ssh-to-age
sops <host>/secrets/<file>.yaml
```

`.sops.yaml` (if present at repo root, otherwise inferred) defines which age keys may decrypt which paths. When adding a new host, derive its age pubkey from the SSH host key with `ssh-to-age` and add it to the `.sops.yaml` creation rules before re-encrypting.