incus-contrib/.claude/rules/proxmox-ssh-rules.md

Proxmox SSH Root Access -- STRICT SAFETY RULES

Root SSH to Proxmox host is for diagnostics only. Password: PROXMOX_ROOT_PASSWORD in env file.

MANDATORY RULES -- violation is unacceptable

1. Screenshots only: ONLY use SSH for qm monitor <vmid> screendump. No other commands without explicit user instruction.
2. Test VMs only: screenshot VMs in VMID range 400-499 or 800-939, or VMs in the IncusLab pool created by our scripts.
3. No modifications: NEVER qm set/stop/start/destroy, pct, zfs, systemctl, or ANY write operation on the host.
4. Do not touch the dev VM: user's dev VM is on the same host. Do not interact with it in any way.
5. No config access: do not read/modify /etc/pve/, storage/network configs, user/ACL settings, or host-level configuration.
6. Transparency: every SSH command is visible. If user rejects, stop.
7. Only during active tests: only when test VMs are deployed.

Permitted commands (exhaustive)

Use incusos/helpers/proxmox-screenshot VMID instead of raw SSH.

Manual fallback (only if helper unavailable):

sshpass -p "$PROXMOX_ROOT_PASSWORD" ssh -o StrictHostKeyChecking=no \
    root@<host> "echo 'screendump /tmp/vm-<vmid>-screen.ppm' | qm monitor <vmid>"
sshpass -p "$PROXMOX_ROOT_PASSWORD" scp -o StrictHostKeyChecking=no \
    root@<host>:/tmp/vm-<vmid>-screen.ppm /tmp/
sshpass -p "$PROXMOX_ROOT_PASSWORD" ssh -o StrictHostKeyChecking=no \
    root@<host> "rm -f /tmp/vm-<vmid>-screen.ppm"

Technical notes

• screendump is root-only in PVE 9 HMP. API tokens cannot do it.
• Use .ppm format -- PVE 9.1 lacks libpng for PNG screendump.
• PPM ~3 MB -> PNG ~20 KB via python3 -c "from PIL import Image; ...".