How do I authenticate?

Create an API token, export PVE_TOKEN, and use the Authorization header (PVEAPIToken) in your curl requests.

Which endpoints differentiate VM vs LXC operations?

Use /nodes/{node}/qemu for VMs and /nodes/{node}/lxc for containers; VM creation uses fields like vmid, memory, cores, and ostype, while LXC uses ostemplate and rootfs specifics.

What prerequisites should I have before starting?

Install curl and jq, set PVE_URL, obtain a PVE_TOKEN, and consider creating the token with Privilege Separation disabled if your setup requires broader access as per the guidance.

Proxmox Full

Scanned

@mSarheed

npx machina-cli add skill @mSarheed/proxmox-full --openclaw

Files (1)

SKILL.md

8.2 KB

Proxmox VE - Full Management

Complete control over Proxmox VE hypervisor via REST API.

Setup

export PVE_URL="https://192.168.1.10:8006"
export PVE_TOKEN="user@pam!tokenid=secret-uuid"

Create API token: Datacenter → Permissions → API Tokens → Add (uncheck Privilege Separation)

Auth Header

AUTH="Authorization: PVEAPIToken=$PVE_TOKEN"

Cluster & Nodes

# Cluster status
curl -sk -H "$AUTH" "$PVE_URL/api2/json/cluster/status" | jq

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

# Node details
curl -sk -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/status" | jq

List VMs & Containers

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

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

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

VM/Container Control

# Start
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}/status/start"

# Stop (immediate)
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}/status/stop"

# Shutdown (graceful)
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}/status/shutdown"

# Reboot
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}/status/reboot"

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

Create LXC Container

# Get next available VMID
NEWID=$(curl -sk -H "$AUTH" "$PVE_URL/api2/json/cluster/nextid" | jq -r '.data')

# Create container
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/lxc" \
  -d "vmid=$NEWID" \
  -d "hostname=my-container" \
  -d "ostemplate=local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst" \
  -d "storage=local-lvm" \
  -d "rootfs=local-lvm:8" \
  -d "memory=1024" \
  -d "swap=512" \
  -d "cores=2" \
  -d "net0=name=eth0,bridge=vmbr0,ip=dhcp" \
  -d "password=changeme123" \
  -d "start=1"

LXC Parameters:

Param	Example	Description
vmid	200	Container ID
hostname	myct	Container hostname
ostemplate	local:vztmpl/debian-12-...	Template path
storage	local-lvm	Storage for rootfs
rootfs	local-lvm:8	Root disk (8GB)
memory	1024	RAM in MB
swap	512	Swap in MB
cores	2	CPU cores
net0	name=eth0,bridge=vmbr0,ip=dhcp	Network config
password	secret	Root password
ssh-public-keys	ssh-rsa ...	SSH keys (URL encoded)
unprivileged	1	Unprivileged container
start	1	Start after creation

Create VM

# Get next VMID
NEWID=$(curl -sk -H "$AUTH" "$PVE_URL/api2/json/cluster/nextid" | jq -r '.data')

# Create VM
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu" \
  -d "vmid=$NEWID" \
  -d "name=my-vm" \
  -d "memory=2048" \
  -d "cores=2" \
  -d "sockets=1" \
  -d "cpu=host" \
  -d "net0=virtio,bridge=vmbr0" \
  -d "scsi0=local-lvm:32" \
  -d "scsihw=virtio-scsi-pci" \
  -d "ide2=local:iso/ubuntu-22.04.iso,media=cdrom" \
  -d "boot=order=scsi0;ide2;net0" \
  -d "ostype=l26"

VM Parameters:

Param	Example	Description
vmid	100	VM ID
name	myvm	VM name
memory	2048	RAM in MB
cores	2	CPU cores per socket
sockets	1	CPU sockets
cpu	host	CPU type
net0	virtio,bridge=vmbr0	Network
scsi0	local-lvm:32	Disk (32GB)
ide2	local:iso/file.iso,media=cdrom	ISO
ostype	l26 (Linux), win11	OS type
boot	order=scsi0;ide2	Boot order

Clone VM/Container

# Clone VM
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}/clone" \
  -d "newid=201" \
  -d "name=cloned-vm" \
  -d "full=1" \
  -d "storage=local-lvm"

# Clone LXC
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/lxc/{vmid}/clone" \
  -d "newid=202" \
  -d "hostname=cloned-ct" \
  -d "full=1" \
  -d "storage=local-lvm"

Clone Parameters:

Param	Description
newid	New VMID
name/hostname	New name
full	1=full clone, 0=linked clone
storage	Target storage
target	Target node (for migration)

Convert to Template

# Convert VM to template
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}/template"

# Convert LXC to template
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/lxc/{vmid}/template"

Snapshots

# List snapshots
curl -sk -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}/snapshot" | jq '.data[] | {name, description}'

# Create snapshot
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}/snapshot" \
  -d "snapname=before-update" \
  -d "description=Snapshot before system update"

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

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

Backups

# Start backup
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/vzdump" \
  -d "vmid={vmid}" \
  -d "storage=local" \
  -d "mode=snapshot" \
  -d "compress=zstd"

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

# Restore backup
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu" \
  -d "vmid=300" \
  -d "archive=local:backup/vzdump-qemu-100-2024_01_01-12_00_00.vma.zst" \
  -d "storage=local-lvm"

Storage & Templates

# List storage
curl -sk -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/storage" | jq '.data[] | {storage, type, avail, used}'

# List available templates
curl -sk -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/storage/local/content?content=vztmpl" | jq '.data[] | .volid'

# List ISOs
curl -sk -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/storage/local/content?content=iso" | jq '.data[] | .volid'

# Download template
curl -sk -X POST -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/aplinfo" \
  -d "storage=local" \
  -d "template=debian-12-standard_12.2-1_amd64.tar.zst"

Tasks

# Recent tasks
curl -sk -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/tasks?limit=10" | jq '.data[] | {upid, type, status}'

# Task status
curl -sk -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/tasks/{upid}/status" | jq

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

Delete VM/Container

# Delete VM (must be stopped)
curl -sk -X DELETE -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}"

# Delete LXC
curl -sk -X DELETE -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/lxc/{vmid}"

# Force delete (purge)
curl -sk -X DELETE -H "$AUTH" "$PVE_URL/api2/json/nodes/{node}/qemu/{vmid}?purge=1&destroy-unreferenced-disks=1"

Quick Reference

Action	Endpoint	Method
List nodes	/nodes	GET
List VMs	/nodes/{node}/qemu	GET
List LXC	/nodes/{node}/lxc	GET
Create VM	/nodes/{node}/qemu	POST
Create LXC	/nodes/{node}/lxc	POST
Clone	/nodes/{node}/qemu/{vmid}/clone	POST
Start	/nodes/{node}/qemu/{vmid}/status/start	POST
Stop	/nodes/{node}/qemu/{vmid}/status/stop	POST
Snapshot	/nodes/{node}/qemu/{vmid}/snapshot	POST
Delete	/nodes/{node}/qemu/{vmid}	DELETE
Next ID	/cluster/nextid	GET

Notes

Use -k for self-signed certs
API tokens don't need CSRF
Replace {node} with node name (e.g., pve)
Replace {vmid} with VM/container ID
Use qemu for VMs, lxc for containers
All create/clone operations return task UPID for tracking

Source

git clone https://clawhub.ai/mSarheed/proxmox-fullView on GitHub

Overview

Proxmox Full provides complete programmatic control over Proxmox VE through its REST API. It enables managing VMs and LXC containers, snapshots, backups, storage, and templates to automate and scale Proxmox infrastructure.

How This Skill Works

Authenticate using an API token (PVE_TOKEN) and send requests with the Authorization header. The skill demonstrates common REST calls to list resources, create VMs/containers, and manage lifecycle and storage via the PVE API endpoints for VMs (qemu) and containers (lxc).

When to Use It

You need to deploy new VMs or LXC containers on Proxmox nodes.
You want to automate lifecycle operations like start, stop, shutdown, or reboot.
You need to manage OS templates, clones, and templates for rapid provisioning.
You want to fetch cluster/nodes status and resource usage for monitoring.
You’re scripting backups, snapshots, and storage-related tasks to enforce data protection.

Quick Start

Step 1: Set PVE_URL and PVE_TOKEN, then export AUTH="Authorization: PVEAPIToken=$PVE_TOKEN"
Step 2: Get the next VMID with curl -sk -H "$AUTH" "$PVE_URL/api2/json/cluster/nextid"
Step 3: Create a VM or LXC using the appropriate endpoint (/nodes/{node}/qemu or /nodes/{node}/lxc) with the required fields

Best Practices

Use cluster/nextid to reliably generate unique VMID/containers before creation.
Always use the correct endpoint: /nodes/{node}/qemu for VMs and /nodes/{node}/lxc for containers.
Create an API token with appropriate privileges and, when needed, disable Privilege Separation as documented.
Validate responses with curl/jq and implement error handling for API limits and timeouts.
Plan backups and snapshots ahead of changes; map storage to ensure rootfs and data disks are correctly configured.

Example Use Cases

List cluster status and node details to assess readiness.
Get the next VMID and create a new VM with 2GB RAM, 2 cores on node 'node1'.
Create an LXC container using an ostemplate and map storage to local-lvm with network set to DHCP.
Start a VM via REST after creation to verify provisioning.
Retrieve cluster resources to monitor VM/LXC usage across the cluster.

Frequently Asked Questions

Add this skill to your agents