playbooks

home / skills / openclaw / skills / proxmox-full

proxmox-full skill

/skills/msarheed/proxmox-full

This skill manages Proxmox VE infrastructure end-to-end, enabling you to create, clone, start, stop, back up, and snapshot VMs and LXC containers.

npx playbooks add skill openclaw/skills --skill proxmox-full

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
8.2 KB
---
name: proxmox-full
description: Complete Proxmox VE management - create/clone/start/stop VMs and LXC containers, manage snapshots, backups, storage, and templates. Use when user wants to manage Proxmox infrastructure, virtual machines, or containers.
metadata: {"clawdbot":{"emoji":"🖥️","homepage":"https://www.proxmox.com/","requires":{"bins":["curl","jq"],"env":["PVE_TOKEN"]},"primaryEnv":"PVE_TOKEN"}}
---

# Proxmox VE - Full Management

Complete control over Proxmox VE hypervisor via REST API.

## Setup

```bash
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

```bash
AUTH="Authorization: PVEAPIToken=$PVE_TOKEN"
```

---

## Cluster & Nodes

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

Overview

This skill provides complete Proxmox VE management via the Proxmox REST API. It lets you create, clone, start, stop, snapshot, back up, restore, and delete VMs and LXC containers, plus manage storage and templates. Use it to automate and script day-to-day Proxmox operations at scale.

How this skill works

The skill issues authenticated REST calls to the Proxmox API endpoints (nodes, qemu, lxc, cluster, storage, vzdump) and returns task UPIDs for long-running operations. It supports VM and container lifecycle actions, snapshot and backup workflows, cloning and templating, storage queries, and task monitoring. It expects a PVE URL and API token for authentication and handles standard responses and task polling.

When to use it

  • Automate VM and LXC lifecycle (create, start, stop, reboot).
  • Provision new VMs or containers from templates or ISOs.
  • Clone machines for testing or scale-out via full or linked clones.
  • Create and manage snapshots and backups before risky changes.
  • List and inspect cluster, node, storage, and task state programmatically.

Best practices

  • Use API tokens scoped to minimal privileges and rotate them regularly.
  • Call /cluster/nextid to avoid VMID conflicts when creating resources.
  • Track returned task UPIDs to poll task status and read logs before assuming completion.
  • Prefer snapshots and snapshot-mode backups before system updates or configuration changes.
  • Use storage- and node-targeting for clones and restores to control placement and capacity.

Example use cases

  • Provision a new LXC using a stored template, configure networking, and start it automatically.
  • Create a VM from ISO, attach disk to local-lvm, and convert a tested VM into a template for future clones.
  • Full clone a production VM to a test node, then snapshot and run upgrade tests before rollback.
  • Start scheduled backups of critical VMs with zstd compression and restore selected archives to a new VMID on another node.
  • List cluster resources and node health metrics to feed monitoring dashboards.

FAQ

How do I authenticate requests?

Set PVE_URL and a PVE API token, then send Authorization: PVEAPIToken=token in request headers. Tokens avoid CSRF requirements.

How can I track long-running operations?

Most create/clone/backup actions return a task UPID. Poll the task status endpoint and fetch task logs to confirm completion and inspect errors.