| name | proxmox-overview |
| description | Entry point and router for managing Proxmox VE. Load this first for any Proxmox request — it establishes the version check, the API-first-vs-SSH decision, how to authenticate, and which specific Proxmox skill to use (VMs, LXC, storage/backups, updates, or host-level config like GPU passthrough). |
Proxmox VE — overview & routing
Start here for any Proxmox task. This skill sets up how to connect, forces a version check, and routes to the
right specific skill. It is API-first and obeys the homelab-core homelab-core:homelab-safety and
homelab-core:homelab-research policies.
Step 1 — version check (always first)
Proxmox 8.x and 9.x differ in real, breaking ways (removed kernel modules, VNC proxy changes, IOMMU
enforcement). Before acting on anything non-obvious:
GET /version via the API (scripts/pve-api.sh GET /version), or pveversion -v on the node.- Scope all research to that version (see
homelab-research + reference/version-notes.md).
Step 2 — connect via the API (preferred)
Two ways, in order of preference:
- MCP server (if the user configured one — see the plugin's
.mcp.json, e.g. ProxmoxMCP-Plus). Use its
tools directly.
- REST API with an API token via
scripts/pve-api.sh. See
proxmox-api for auth setup, endpoints, and examples.
Use API tokens (PVEAPIToken=user@realm!name=secret), not passwords — stateless, no CSRF, revocable.
Step 3 — decide API vs SSH
| Want to… | Use |
|---|
| Start/stop/create/delete/migrate VMs & LXC, snapshots | API → proxmox-vms, proxmox-lxc |
| List/inspect storage, run/restore backups (vzdump/PBS) | API → proxmox-storage-backups |
| Check/apply updates, repo status, node health | API → proxmox-updates |
| Cluster status, tasks, resource usage | API → proxmox-api |
GPU/PCIe passthrough, lxc.idmap, hookscripts, kernel/VFIO, /etc/network/interfaces | SSH → proxmox-host-config (confirm SSH drop first) |
If the API can do it, do not use SSH. SSH is only for the host-level skill, and only after the user
approves the SSH drop per the safety policy.
Step 4 — apply the safety gate
Any change (start/stop/create/delete/config edit) needs a batched plain-language summary and approval first.
Destructive operations (delete VM/CT, remove storage, restore-over-existing) must call out irreversibility
and data risk. See homelab-safety. Snapshot before risky changes when possible.
Specific skills in this plugin
proxmox-api — auth (tokens), the pve-api.sh helper, common endpoints, tasks.proxmox-vms — QEMU/KVM VM lifecycle, config, snapshots, cloud-init.proxmox-lxc — LXC container lifecycle, privileged vs unprivileged, mounts.proxmox-storage-backups — storage types, vzdump, PBS, restore.proxmox-updates — package updates, repos, upgrade gotchas.proxmox-host-config — SSH-level: config files, GPU passthrough, idmap.
Reference
