name: proxmox-ops
description: |
Ops-focused Proxmox VE management via REST API — monitor, control, provision, and troubleshoot VMs and LXC containers with battle-tested operational patterns.

Use when asked to:
- List, start, stop, restart VMs or LXC containers
- Check node status, cluster health, or resource usage
- Create, clone, or delete VMs and containers
- Manage snapshots, backups, storage, or templates
- Resize disks (API + in-guest filesystem steps)
- Query guest agent for IP addresses
- View tasks or system event logs

Includes helper script (pve.sh) with auto node discovery from VMID, operational safety gates (read-only vs reversible vs destructive), vmstate snapshot warnings, post-resize guest filesystem steps, and a separate provisioning reference.

Requires: curl, jq.
Credentials: PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET — set as env vars or stored in ~/.proxmox-credentials (sourced at runtime, user-created, mode 600).
Writes: ~/.proxmox-credentials (user-created, API token, mode 600).
Network: connects to user-configured Proxmox host only (HTTPS, TLS verification disabled for self-signed certs).

Helper script: scripts/pve.sh (relative to this skill)
Configuration: ~/.proxmox-credentials
metadata: { "openclaw": { "emoji": "🖥️", "homepage": "https://github.com/eddygk/proxmox-ops-skill", "requires": { "bins": ["curl", "jq"] }, "os": ["darwin", "linux"] } }

Proxmox VE Management

First-Time Setup

Create a credential file at ~/.proxmox-credentials:

cat > ~/.proxmox-credentials <<'EOF'
PROXMOX_HOST=https://<your-proxmox-ip>:8006
PROXMOX_TOKEN_ID=user@pam!tokenname
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
EOF
chmod 600 ~/.proxmox-credentials

Alternative: Set PROXMOX_HOST, PROXMOX_TOKEN_ID, and PROXMOX_TOKEN_SECRET as environment variables directly (useful for CI/agent contexts). The helper script checks env vars first, then falls back to sourcing ~/.proxmox-credentials.

Create API token in Proxmox: Datacenter → Permissions → API Tokens → Add. Use least-privilege: only grant the permissions your workflow requires (e.g., PVEAuditor for read-only monitoring, PVEVMAdmin for VM control). Disable Privilege Separation only if your workflow requires full API access.

Auth Header

source ~/.proxmox-credentials
AUTH="Authorization: PVEAPIToken=$PROXMOX_TOKEN_ID=$PROXMOX_TOKEN_SECRET"

Helper Script

scripts/pve.sh auto-discovers nodes from VMID — no need to specify the node for most operations.

pve.sh status              # Cluster nodes overview
pve.sh vms [node]          # List all VMs (optionally filter by node)
pve.sh lxc <node>          # List LXC containers on node
pve.sh start <vmid>        # Start VM/LXC
pve.sh stop <vmid>         # Force stop VM/LXC
pve.sh shutdown <vmid>     # Graceful shutdown VM/LXC
pve.sh reboot <vmid>       # Reboot VM/LXC
pve.sh snap <vmid> [name]  # Create snapshot (disk-only, safe)
pve.sh snapshots <vmid>    # List snapshots
pve.sh tasks <node>        # Show recent tasks
pve.sh storage <node>      # Show storage status

Workflow

1. Load credentials from ~/.proxmox-credentials
2. Determine operation type:
3. Read-only (status, list, storage, tasks) → Execute directly
4. Reversible (start, stop, reboot, snapshot) → Execute, note UPID for tracking
5. Destructive (delete VM, resize disk, rollback snapshot) → Confirm with user first
6. Query Proxmox API via curl + API token auth
7. Parse JSON with jq
8. Track async tasks — create/clone/backup operations return UPID

Common Operations

Cluster & Nodes

# Cluster status
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/cluster/status" | jq

# List nodes with CPU/memory
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes" | jq '.data[] | {node, status, cpu, mem: (.mem/.maxmem*100|round)}'

List VMs & Containers

# Cluster-wide (all VMs + LXC)
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/cluster/resources?type=vm" | jq '.data[] | {node, vmid, name, type, status}'

# VMs on specific node
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu" | jq '.data[] | {vmid, name, status}'

# LXC on specific node
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/lxc" | jq '.data[] | {vmid, name, status}'

VM/Container Control

# Start / Stop / Shutdown / Reboot
curl -ks -X POST -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/status/start"
curl -ks -X POST -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/status/stop"
curl -ks -X POST -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/status/shutdown"
curl -ks -X POST -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/status/reboot"

# For LXC: replace /qemu/ with /lxc/

Snapshots

⚠️ vmstate parameter: Do NOT include vmstate=1 unless you specifically need to preserve running process state.
- vmstate=1 freezes the VM and causes heavy I/O — can starve other guests on the same node
- For pre-change backups, omit vmstate (defaults to disk-only, no I/O spike)

# List snapshots
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/snapshot" | jq

# Create snapshot (disk-only, safe)
curl -ks -X POST -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/snapshot" \
  -d "snapname=snap1" -d "description=Before update"

# Rollback
curl -ks -X POST -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/snapshot/{snapname}/rollback"

# Delete snapshot
curl -ks -X DELETE -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/snapshot/{snapname}"

Disk Resize

# Get current disk config
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/config" | jq

# Resize disk (use absolute size, NOT relative — +10G fails regex validation)
curl -ks -X PUT -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/resize" \
  -d "disk=scsi0" -d "size=20G" | jq

Post-resize inside VM:
1. Fix GPT: parted /dev/sda print → Fix
2. Resize partition: parted /dev/sda resizepart 3 100%
3. If LVM: pvresize /dev/sda3 && lvextend -l +100%FREE /dev/vg/root
4. Resize filesystem: resize2fs /dev/mapper/vg-root (ext4) or xfs_growfs / (xfs)

Guest Agent (IP Discovery)

# Get VM network interfaces (requires qemu-guest-agent)
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/qemu/{vmid}/agent/network-get-interfaces" | \
  jq -r '.data.result[] | select(.name != "lo") | .["ip-addresses"][] | select(.["ip-address-type"] == "ipv4") | .["ip-address"]' | head -1

Always query guest agent for current IP — don't hardcode IPs.

Storage & Backups

# List storage
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/storage" | jq '.data[] | {storage, type, active, used_fraction: (.used/.total*100|round|tostring + "%")}'

# List backups
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/storage/{storage}/content?content=backup" | jq

# Start backup
curl -ks -X POST -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/vzdump" \
  -d "vmid={vmid}" -d "storage={storage}" -d "mode=snapshot"

Tasks

# Recent tasks
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/tasks" | jq '.data[:10] | .[] | {upid, type, status, user}'

# Task log
curl -ks -H "$AUTH" "$PROXMOX_HOST/api2/json/nodes/{node}/tasks/{upid}/log" | jq -r '.data[].t'

Provisioning

For create VM, create LXC, clone, convert to template, and delete operations:

→ See references/provisioning.md

Security Notes

• Credential file (~/.proxmox-credentials) is user-created, not auto-generated by this skill. Must be mode 600 (chmod 600 ~/.proxmox-credentials). Rotate tokens immediately if exposed
• TLS verification disabled (-k / --insecure) — Proxmox VE uses self-signed certificates by default (Proxmox docs). If you deploy a trusted CA cert on your Proxmox node, remove the -k flag from curl commands and pve.sh
• Least-privilege tokens — create tokens with only the roles your workflow needs. PVEAuditor for monitoring, PVEVMAdmin for VM ops. Full-access tokens are not required for most operations
• Network scope — all API calls target PROXMOX_HOST only. No external endpoints. Verify by reviewing scripts/pve.sh (small, readable). In agent contexts, restrict network access to your Proxmox hosts only
• API tokens don't need CSRF tokens for POST/PUT/DELETE
• Power and delete operations are destructive — confirm with user first
• Never expose credentials in responses

Notes

• Replace {node}, {vmid}, {storage}, {snapname} with actual values
• Task operations return UPID for tracking async jobs
• Use qemu for VMs, lxc for containers in endpoint paths