Proxmox-Coolify-Manager/agent/SKILL.md

Proxmox Manager Agent

Use this project-local skill when helping manage the local Proxmox host.

Scope

• Host: 192.168.0.200, Proxmox VE 9.1.1, single node
• Node: thinkcentre
• Main Docker LXC: 102 (coolify) — running, 68 containers
• Secondary LXC: 100 (hermes) — running (commit 5d3c15aaa, MiniMax-M3, IPs: 192.168.3.23 / 192.168.3.15)
• No QEMU VMs
• Access methods: SSH first, Proxmox REST API when token env vars are present (they are not loaded today — see TOOLS.md)

Startup routine

1. Load secrets: . .\.env.local.ps1.
2. Read docs/TOOL-INDEX.md — the canonical tool catalog. Its §1 lists four gotchas that produce silently wrong results. The one that bites hardest here: Invoke-ProxmoxSsh.ps1 mangles nested quotes, so anything with two levels of quoting needs base64 (see TOOLS.md).
3. Read docs/proxmox-inventory.md for current state, plus the relevant runbook in docs/runbooks/.
4. Run .\scripts\Test-ProxmoxConnection.ps1 before operational work.
5. For fresh state, run .\scripts\Get-ProxmoxInventory.ps1.
6. Prefer .\scripts\Invoke-ProxmoxSsh.ps1 -Command "<command>" for remote commands.

Safety policy

• Default to read-only diagnostics.
• Ask for explicit confirmation before any command that can stop, restart, delete, resize, update, create privileged access, change firewall/network/storage, or edit production configuration.
• Never place passwords, API token secrets, private keys, cookies, or tickets in docs.
• Do not run broad destructive commands from generated strings.
• For risky actions, gather current state first and state rollback options.

Safe read-only commands

.\scripts\Invoke-ProxmoxSsh.ps1 -Command "hostname && pveversion"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct list && qm list"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pvesh get /cluster/resources"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker stats --no-stream"

Common workflows

• Host health: run inventory, then inspect disk, memory, load, failed services.
• LXC health: inspect pct status <vmid>, config, resources, logs if relevant.
• Coolify/Docker: operate through pct exec 102 -- docker ....
• API checks: use Invoke-ProxmoxApi from scripts/ProxmoxAgent.ps1 after env token is loaded.