Archived
beatzaplentyandClaude Sonnet 5
302c3b671f
Remove the nonexistent kuma host and add the missing linode-minimal host across README, AGENTS.md, docs, and CI eval workflows so they match flake.nix's nixosConfigurations. Also add CLAUDE.md with architecture/safety guidance for future Claude Code sessions. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
115 lines
5.2 KiB
Markdown
115 lines
5.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Repo purpose
|
|
|
|
Flake-based NixOS configuration for Wayne's LAN servers and workstation. There is
|
|
no application code here — changes are Nix module edits that affect real
|
|
machines when deployed.
|
|
|
|
## Safety rules (read before touching anything)
|
|
|
|
- **Never** run `nixos-rebuild switch|boot|test`, `nixos-install`, `parted`,
|
|
`mkfs`, `mkswap`, `swapon`, `mount`, or any other destructive disk/deploy
|
|
command from an agent session, even if asked indirectly. Deployment is done
|
|
manually by the operator on the target host.
|
|
- Validation is limited to evaluation, linting, formatting checks, and
|
|
`nix build --dry-run --no-link`.
|
|
- Do not add secrets, tokens, private keys, or new password hashes to the repo.
|
|
- This repo currently contains **committed password hashes** (e.g.
|
|
`prepare.sh`, `hosts/nixos/configuration.nix`) and SSH public keys (e.g.
|
|
`modules/nix-cache/server.nix`). The hashes are known tech debt — do not use
|
|
them as a template for new hosts, and flag any *new* secret-like string you
|
|
encounter instead of committing it.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# One-time environment bootstrap (installs Nix if missing, prints hosts)
|
|
bash scripts/codex-setup.sh
|
|
|
|
# Full validation: secret grep, nixpkgs-fmt --check, statix lint, eval all hosts
|
|
bash scripts/codex-maintenance.sh
|
|
|
|
# Same, plus a dry-run build (no result symlink) of every host's toplevel
|
|
bash scripts/codex-maintenance.sh dry-run
|
|
|
|
# List the hosts the flake currently exposes
|
|
nix eval --json .#nixosConfigurations --apply builtins.attrNames | jq -r '.[]'
|
|
|
|
# Evaluate a single host without building (fast sanity check)
|
|
nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
|
|
|
|
# Dry-run build a single host
|
|
nix build --dry-run --no-link .#nixosConfigurations.<host>.config.system.build.toplevel
|
|
```
|
|
|
|
Formatting/lint tools (`nixpkgs-fmt`, `statix`) are not installed locally; the
|
|
maintenance script pulls them via `nix run github:NixOS/nixpkgs/nixos-25.11#<tool>`.
|
|
There is no test suite — "correctness" here means the flake evaluates and
|
|
`nixpkgs-fmt`/`statix` are clean.
|
|
|
|
## Architecture
|
|
|
|
`flake.nix` is the single entry point. It defines one `nixosConfigurations.<host>`
|
|
attribute per machine, each built the same way:
|
|
|
|
```
|
|
nixosSystem {
|
|
modules = [
|
|
disko.nixosModules.disko
|
|
./hosts/<host>/configuration.nix # host-specific config
|
|
./modules/hardware-configuration/vm/<proxmox|linode>.nix
|
|
home-manager.nixosModules.home-manager { ... }
|
|
];
|
|
}
|
|
```
|
|
|
|
Hosts currently defined in `flake.nix`: `nixos`, `docker`, `server`,
|
|
`nix-cache`, `nix-minimal`, `pxe-boot`, `linode-minimal`. Treat `flake.nix` as
|
|
the source of truth for which hosts exist — `README.md`, `AGENTS.md`,
|
|
`docs/flake-lock-automation.md`, and the CI eval workflows
|
|
(`.github/workflows/check-nixos.yml`, `.gitea/workflows/check-nixos.yml`) list
|
|
hosts by hand and can drift from it, so re-check them against `flake.nix` when
|
|
adding or removing a host.
|
|
|
|
### Composition pattern
|
|
|
|
Every host's real configuration lives in `hosts/<host>/configuration.nix`,
|
|
which is a thin list of `imports` pulling in reusable pieces from `modules/`:
|
|
|
|
- `modules/common/configuration.nix` — base NixOS config imported by (almost)
|
|
every host: locale, users, nix settings, git. Nearly always the first import.
|
|
- `modules/common/home.nix` / `hosts/<host>/home.nix` — Home Manager config for
|
|
the `nixos` user; the `nixos` workstation has its own, other hosts share
|
|
`modules/common/home.nix`.
|
|
- `modules/disko/proxmox.nix` — declarative disk layout (GPT: ESP + swap +
|
|
ext4 root) via disko, used by all Proxmox-VM hosts.
|
|
- `modules/boot/efi.nix` — systemd-boot + EFI vars, paired with the disko module.
|
|
- `modules/hardware-configuration/vm/{proxmox,linode}.nix` — hypervisor-specific
|
|
hardware config, wired in from `flake.nix` (not from the host file).
|
|
- `modules/nix-cache/{client,server}.nix` + `modules/remote-builder-client.nix` —
|
|
binary cache substituter + SSH remote-builder wiring; see `docs/nix-cache.md`
|
|
for the full design (per-host local stores, no shared `/nix/store`, and how
|
|
the `nixremote` signing/SSH keys fit together).
|
|
- `modules/tailscale/`, `modules/docker/`, `modules/beszel/`,
|
|
`modules/services/*` — single-purpose, single-host feature modules (e.g.
|
|
`docker/enable-service.nix`, `services/zfs/enable-service.nix`,
|
|
`beszel/enable-agent.nix` for monitoring). Grep `hosts/*/configuration.nix`
|
|
for the `imports` list to see which modules apply to a given host.
|
|
|
|
New host = new `hosts/<name>/configuration.nix` + a matching block added to
|
|
`flake.nix`'s `nixosConfigurations`, composed from existing `modules/*` pieces
|
|
rather than duplicating config.
|
|
|
|
### Other docs worth reading before touching these areas
|
|
|
|
- `docs/nix-cache.md` — nix-cache binary cache/remote-builder design and key
|
|
handling.
|
|
- `docs/pxe-boot.md` — the `pxe-boot` host's iPXE/TFTP/HTTP boot chain and
|
|
directory layout under `/srv/pxe`.
|
|
- `docs/flake-lock-automation.md` — how `flake.lock` updates flow through CI
|
|
(scheduled `nix flake update` PR + host-eval-on-PR workflow) and why hosts
|
|
should track the committed lock file rather than `nixos-rebuild --upgrade-all`.
|