debian-configuration/proxmox/CLAUDE.md

CLAUDE.md

Guidance for Claude Code working in this repo. IMPORTANT: these instructions OVERRIDE any default behavior and must be followed exactly as written.

Repo purpose

Base configuration/hardening toolset and planning docs for Proxmox VE hosts (scripts/, config/, docs/) — see README.md and docs/00-overview.md. Scripts in this repo are meant to be run on the target Proxmox host itself (as root), not orchestrated remotely.

Two Proxmox nodes: pve1 (production) and pve-test (sandbox)

Two SSH-reachable Proxmox nodes exist on the LAN. They are not interchangeable — see docs/05-node-roles.md for full background on what each one is and why.

pve1 (production — off-limits to Claude by default)

A real, live Proxmox node hosting production VMs/containers (see docs/05-node-roles.md for the current guest list) — not a sandbox, and not Claude's to touch by default.

• Off-limits at all times unless the operator has given explicit, same-session instructions to act on this specific host. That authorization is scoped to the task it was given for — don't carry it forward to unrelated later work in the same conversation, and never assume it from a previous session.
• Read-only for existing state is always fine, authorization or not. SSH in (or use pvesm, qm list, pct list, qm config, pct config, the Proxmox API, etc.) to inspect config, storage, and any existing VM/container freely.
• Never modify, stop, restart, delete, reconfigure, or create anything on this node (qm set, pct set, qm destroy, pct destroy, qm stop, pct stop, qm create, pct create, snapshot operations, storage changes, running any script in this repo against it, etc.) without that explicit go-ahead. Use pve-test for anything exploratory instead.
• If a guest on pve1 is HA-managed, be aware of the self-fence hazard described in docs/05-node-roles.md's cluster-teardown section before doing anything that could cost the node quorum.

pve-test (sandbox — Claude's default target)

A separate node set aside for testing — safe to create, interrogate, and destroy scratch VMs/containers on without asking first.

• Test VMs/containers are allowed, but must be torn down. Anything created this way must be destroyed again in the same session, before ending the task. Use an obviously-scratch VMID/name.
• Node-level config is still not yours to change by default. Creating/destroying your own scratch guests is fine; Proxmox host config, storage pools, and networking on pve-test itself need the operator's explicit go-ahead too, same as on pve1 — the "sandbox" status covers guest-level experimentation, not the host's own identity. (pve-test's current network config, docs/06-pve-test-wifi-network.md, was applied under exactly that kind of explicit, same-session authorization — it's not a standing invitation to keep changing it further without asking again.)
• Never re-cluster pve-test with pve1 without the operator explicitly asking for it and being aware of the wifi/corosync incompatibility in docs/06-pve-test-wifi-network.md — the two were deliberately de-clustered for this reason once already.

Safety rules

• Any script in scripts/ that isn't audit.sh (read-only) makes real changes when run for real. Don't run one against pve1, or against pve-test's node-level config, without the same-session go-ahead described above. Running a script against pve-test's own guests — a scratch VM/CT you created for this task — doesn't need separate permission.
• Do not commit secrets: SSH private keys, wifi passphrases, sops/age keys, or PVE credentials. scripts/setup-wifi-bond-network.sh takes the SSID/passphrase via environment variables for exactly this reason — never hardcode them into the script or a committed config file.
• Live changes to a node's own management network (the interface/bridge carrying the SSH session you're using) can strand the box — see the "what went wrong once" section in docs/06-pve-test-wifi-network.md before touching pve-test's networking again. Prefer applying via ifreload -a over raw ip link surgery, and arm an auto-revert watchdog first when acting without someone physically at the console.