Manage Proxmox VE VM/CT lifecycle, resource planning, templates, snapshots, storage, VLAN configuration, and troubleshooting. Covers QEMU VMs and LXC containers, clone-based provisioning, VMID numbering, storage pool selection, network bridge setup, and common failure modes.
Use this skill when a Spacebot agent needs to create, manage, troubleshoot, or plan Proxmox VE virtual machines and LXC containers. This includes day-to-day lifecycle operations, template-based provisioning, snapshot management, resource capacity planning, storage selection, and network/VLAN configuration.
This playbook separates five commonly conflated areas:
This skill depends on the following Spacebot MCP tools:
| Tool | Purpose | Confirmation Required |
|---|---|---|
proxmox.node.list | List cluster nodes with CPU, memory, uptime | No |
proxmox.node.status | Detailed node status | No |
proxmox.vm.list | List VMs/CTs on a node (filter by qemu/lxc) | No |
proxmox.vm.status | Detailed VM/CT status (CPU, memory, disk, network I/O) | No |
proxmox.vm.start | Start a VM/CT | No |
proxmox.vm.stop | Immediate (force) stop of a VM/CT; does not attempt graceful shutdown | Yes |
proxmox.vm.create | Create a new VM/CT | Yes |
proxmox.vm.clone | Clone a VM from a template or existing VM | No |
proxmox.vm.delete | Permanently delete a VM/CT | Yes |
proxmox.vm.snapshot.list | List snapshots for a VM/CT | No |
proxmox.vm.snapshot.create | Create a snapshot | No |
proxmox.vm.snapshot.rollback | Rollback to a previous snapshot (current state lost) | Yes |
proxmox.storage.list | List storage pools with usage | No |
proxmox.network.list | List network interfaces (bridges, VLANs, bonds) | No |
Additionally, ssh.exec may be used for operations not covered by the Proxmox API (e.g., editing /etc/network/interfaces, running qm or pct CLI commands directly, checking kernel modules).
Throughout this skill, the following placeholders are used. The agent must resolve these to actual values from the user's environment before executing operations.
| Placeholder | Meaning | Example |
|---|---|---|
<PVE_HOST> | Proxmox host config name in Spacebot | pve1 |
<NODE> | Proxmox node name within the cluster | pve1 |
<VMID> | Numeric VM/CT identifier | 100 |
<TEMPLATE_VMID> | VMID of a template to clone from | 9000 |
<STORAGE> | Storage pool name | local-lvm |
<BRIDGE> | Network bridge name | vmbr0 |
<VLAN_TAG> | 802.1Q VLAN tag number | 50 |
<SUBNET_CIDR> | Network range for the VLAN/bridge | 10.0.50.0/24 |
<ISO_PATH> | ISO image path in Proxmox storage | local:iso/ubuntu-24.04.iso |
These patterns recur across Proxmox homelab environments and represent the most common mistakes and best practices.
Always clone from templates; never build from scratch repeatedly.
Use full clones for production, linked clones for ephemeral/test.
VMID numbering conventions prevent collisions and confusion.
100-199 infrastructure VMs, 200-299 application VMs, 300-399 LXC containers, 9000-9099 templates.proxmox.vm.list to see existing VMIDs before creating new ones. The API's /cluster/nextid endpoint returns the next available VMID, but it doesn't respect numbering conventions.Stop a VM before deleting it.
proxmox.vm.status to confirm it's stopped before calling proxmox.vm.delete.Snapshot before risky changes, not after.
pre-upgrade-2024-01-15, before-network-change, not snap1.vmstate=true) allow resuming from the exact point. Without RAM state, the VM will boot fresh from the snapshot's disk state.Storage pool content types matter.
local (directory storage) typically holds ISOs and container templates.local-lvm (LVM thin) typically holds VM disk images and CT rootfs.proxmox.storage.list to see the content field for each pool.LXC containers are lighter than QEMU VMs but less isolated.
The Proxmox API uses async tasks for mutating operations.
qm status <VMID>.Use the first matching category.
Typical signs:
proxmox.vm.start returns an error or the task fails.Most likely causes:
.lock file). Common after a failed migration or snapshot.First actions:
proxmox.node.status -- check available RAM and CPU.proxmox.storage.list -- check storage pool health and free space.proxmox.vm.status -- look for lock indicators in the output.qm config <VMID> to inspect the full VM configuration.Typical signs:
Most likely causes:
vmbr bridge.First actions:
proxmox.vm.status -- confirm it's actually running.proxmox.network.list -- verify the bridge exists and is active.qm config <VMID> to check the net0 line.qm guest exec <VMID> -- ip addr (requires qemu-guest-agent) to check the guest's network config.Typical signs:
proxmox.vm.clone returns a task timeout.Most likely causes:
First actions:
proxmox.storage.list -- check free space on the target storage.Typical signs:
proxmox.vm.snapshot.rollback returns an error.Most likely causes:
First actions:
proxmox.vm.snapshot.list -- confirm the snapshot name exists.qm snapshot <VMID> list for additional detail.Typical signs:
proxmox.storage.list shows a pool at >90% usage.Most likely causes:
First actions:
proxmox.storage.list -- get current usage numbers.proxmox.vm.list -- identify VMs that can be cleaned up.proxmox.vm.snapshot.list on suspect VMs -- identify old snapshots to remove.lvs or zfs list -t snapshot to see actual disk-level usage.Follow in order when provisioning a new workload.
Use LXC if:
Use QEMU if:
Clone from template if:
Create fresh if:
To clone:
proxmox.vm.list (look for template entries or known template VMIDs in the user's convention).proxmox.vm.clone with vmid=<TEMPLATE_VMID>, name=<new-name>, full=true (or false for linked).proxmox.vm.start to boot the new VM.To create fresh:
proxmox.vm.create with cores, memory, storage, ISO, and network parameters.proxmox.vm.start to boot from the ISO.Typical homelab sizing (starting points, adjust based on workload):
| Workload | Type | Cores | RAM | Disk |
|---|---|---|---|---|
| Pi-hole / DNS | LXC | 1 | 256 MB | 4 GB |
| Nginx reverse proxy | LXC | 1 | 512 MB | 8 GB |
| Docker host (light) | QEMU | 2 | 2 GB | 32 GB |
| Docker host (medium) | QEMU | 4 | 8 GB | 64 GB |
| Plex/Jellyfin | QEMU | 4 | 4 GB | 32 GB + media mount |
| Database (Postgres/MySQL) | QEMU | 2 | 4 GB | 32 GB |
| Home Assistant | QEMU | 2 | 2 GB | 32 GB |
| Windows desktop | QEMU | 4 | 8 GB | 64 GB |
Always check available resources first: proxmox.node.status for node-level capacity.
proxmox.storage.list -- see available pools and their free space.images in its content field. CT rootfs needs rootdir. ISOs need iso.proxmox.network.list -- see available bridges and VLANs.virtio,bridge=vmbr0 (standard paravirtualized NIC on the main bridge).virtio,bridge=vmbr0,tag=<VLAN_TAG>.vmbr1 for an internal-only network).The agent should follow the user's established convention. If no convention exists, suggest:
| Range | Purpose |
|---|---|
| 100-199 | Infrastructure VMs (DNS, DHCP, reverse proxy, monitoring) |
| 200-299 | Application VMs (Docker hosts, databases, media servers) |
| 300-399 | LXC containers |
| 400-499 | Test/ephemeral VMs |
| 9000-9099 | Templates (QEMU) |
| 9100-9199 | Templates (LXC) |
Check existing VMIDs with proxmox.vm.list before choosing a new one.
Templates are created via the Proxmox CLI (not the REST API):
# Via SSH to the Proxmox host:
qm template <VMID>
Before converting:
For QEMU templates with cloud-init:
qm set <VMID> --ide2 <STORAGE>:cloudinitqm set <VMID> --ciuser admin --sshkeys ~/.ssh/authorized_keys --ipconfig0 ip=dhcpSnapshot before destructive operations. Before stopping, deleting, or rolling back a VM, create a snapshot first if the VM has unsaved state.
Use dry_run on mutating tools. All mutating Proxmox tools support dry_run=true. Use it to preview the operation before executing.
Confirm destructive tools require two steps. Tools marked with "Confirmation Required" return a confirmation token on first call. The agent must call confirm_operation with both that token and the original tool name to execute. This prevents accidental destruction.
Never delete a template that has linked clones. Linked clones depend on the template's disk. Deleting the template will corrupt all linked clones. Use proxmox.vm.list to check for VMs that might be linked clones before deleting a template.
Stop before delete. A running VM cannot be deleted. Always stop first, verify it's stopped, then delete.
Check node capacity before creating VMs. Don't overcommit RAM beyond ~80% of physical unless the workloads are known to be light. CPU overcommit is generally fine up to 4:1 for typical homelab loads.
Symptoms: HTTP 401 from any Proxmox tool.
Check:
USER@REALM!TOKENID (e.g., root@pam!spacebot).--privsep 0 on the token: if privilege separation is enabled (default), the token needs its own ACL entries.Symptoms: connection refused or TLS handshake failure.
Check:
verify_tls defaults to true in src/config.rs; set verify_tls = false only as an explicit opt-out for trusted self-signed homelab environments, because it disables certificate verification and weakens transport security.Symptoms: HTTP 403 on a tool that previously worked.
Check:
PVEVMAdmin covers most VM operations. PVEAdmin covers everything./vms/100 instead of /). Ensure the token has permissions on the target VMID's path.When managing Proxmox VMs/CTs:
proxmox.node.list, proxmox.vm.list, proxmox.storage.list.proxmox.node.status for CPU/RAM availability.dry_run=true on create/clone/delete before executing.proxmox.vm.status.| Symptom | Most likely fix |
|---|---|
| VM won't start: "not enough memory" | Check proxmox.node.status; reduce VM memory or stop unused VMs |
| VM won't start: "storage not active" | Check proxmox.storage.list; remount or repair the storage pool |
| VM starts but no network | Check net0 config via SSH qm config <VMID>; verify bridge and VLAN tag |
| Clone fails with timeout | Check storage free space; use linked clone for speed; stop source VM first |
| Delete returns error | Stop the VM first, then retry delete |
| API returns 401 | Verify token_id format (USER@REALM!TOKENID) and token_secret |
| API returns 403 on specific VM | Check ACL scope -- token may lack permissions on that VMID path |
| Snapshot rollback fails | Stop the VM first, verify snapshot name with proxmox.vm.snapshot.list |
| Storage pool >90% full | Remove old snapshots, delete unused VMs, check for orphaned disks via SSH |
See supporting reference docs in references/:
vm-lifecycle.md -- step-by-step VM/CT creation, cloning, deletion procedures.snapshot-management.md -- snapshot creation, rollback, and cleanup patterns.storage-planning.md -- storage pool types, content restrictions, and capacity planning.network-configuration.md -- bridge setup, VLAN tagging, and common network patterns.api-troubleshooting.md -- Proxmox API authentication, permissions, and error diagnosis.