nixos/CLAUDE.md

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

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