Proxmox VE Management

First-Time Setup

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

CODEBLOCK0

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

CODEBLOCK1

Helper Script

INLINECODE7 auto-discovers nodes from VMID — no need to specify the node for most operations.

CODEBLOCK2

Workflow

1. 1. Load credentials from INLINECODE8
2. Determine operation type:

1. 3. Query Proxmox API via curl + API token auth
2. Parse JSON with jq
3. Track async tasks — create/clone/backup operations return UPID

Common Operations

Cluster & Nodes

CODEBLOCK3

List VMs & Containers

CODEBLOCK4

VM/Container Control

CODEBLOCK5

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)

CODEBLOCK6

Disk Resize

CODEBLOCK7

Post-resize inside VM:

1. 1. Fix GPT: parted /dev/sda print → Fix
2. Resize partition: INLINECODE12
3. If LVM: INLINECODE13
4. Resize filesystem: resize2fs /dev/mapper/vg-root (ext4) or xfs_growfs / (xfs)

Guest Agent (IP Discovery)

CODEBLOCK8

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

Storage & Backups

CODEBLOCK9

Tasks

CODEBLOCK10

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