Archived
85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
# 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.
|