# 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, Plasma6 + Sway, intel 13th gen, dual wireguard (one in a network namespace for ProtonVPN routed via `dnscrypt-proxy`)
- `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`).

**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.