Run any Skill in Manus with one click

proxmox-api

Stars0

Forks0

UpdatedJune 29, 2026 at 20:30

How to authenticate to and call the Proxmox VE REST API — API token setup, the pve-api.sh helper, common endpoints, and how to poll background tasks. Load this when you need to make Proxmox API calls directly (any VM/LXC/storage/backup/cluster operation that goes through the API rather than an MCP server).

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

Redth

Redth/homelab-assist

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	proxmox-api
description	How to authenticate to and call the Proxmox VE REST API — API token setup, the pve-api.sh helper, common endpoints, and how to poll background tasks. Load this when you need to make Proxmox API calls directly (any VM/LXC/storage/backup/cluster operation that goes through the API rather than an MCP server).

Proxmox VE REST API

The Proxmox API is at https://<host>:8006/api2/json/... and mirrors everything pvesh / the UI can do for lifecycle, storage, backups, cluster, and node management. Use it as the default for Proxmox management.

Authentication — use API tokens

Prefer API tokens over password/ticket auth: stateless, no CSRF token needed, individually revocable, support privilege separation and expiry.

Create one (UI: Datacenter > Permissions > API Tokens, or CLI on the node):

pveum user token add automation@pve mytoken --privsep 1
# grant the token a role on a path, e.g.:
pveum acl modify / --tokens 'automation@pve!mytoken' --roles PVEVMAdmin

Header format:

Authorization: PVEAPIToken=USER@REALM!TOKENNAME=SECRET-UUID

Privilege separation (--privsep 1) means the token gets only the ACLs you grant it, independent of the user. Grant the least privilege the task needs.

The helper script

scripts/pve-api.sh wraps token auth + curl and defaults to GET. Configure via env (never hard-code): PVE_HOST, PVE_PORT, PVE_TOKEN_ID, PVE_TOKEN_SECRET, PVE_VERIFY_SSL.

Store the token secret in the OS secret store (see homelab-core:homelab-secrets), not a dotfile, and inject it per-command — e.g. homelab-secret run PVE_TOKEN_SECRET -- scripts/pve-api.sh GET /version. Never print the token value.

scripts/pve-api.sh GET /version
scripts/pve-api.sh GET /nodes
scripts/pve-api.sh GET /nodes/pve1/qemu
scripts/pve-api.sh GET /cluster/resources | jq '.data[] | {id,type,status}'

Writes (POST/PUT/DELETE) must be approved first per homelab-safety. Only then:

scripts/pve-api.sh POST /nodes/pve1/qemu/100/status/start

Common endpoints (see reference for the full map)

Purpose	Method + path
Version	`GET /version`
Nodes	`GET /nodes` ; node status `GET /nodes/{node}/status`
All resources (VMs/CTs/storage)	`GET /cluster/resources`
List VMs	`GET /nodes/{node}/qemu`
VM status / config	`GET /nodes/{node}/qemu/{vmid}/status/current` ; `.../config`
List LXC	`GET /nodes/{node}/lxc`
Storage	`GET /nodes/{node}/storage` ; content `.../storage/{store}/content`
Tasks	`GET /nodes/{node}/tasks` ; status `.../tasks/{upid}/status`

Full list: reference/api-endpoints.md.

Background tasks (UPID)

Many write operations return a task ID (UPID) and run asynchronously. Don't assume success from the POST response — poll the task:

# the POST returns {"data":"UPID:pve1:..."} ; poll it:
scripts/pve-api.sh GET /nodes/pve1/tasks/UPID:pve1:.../status | jq '.data.status,.data.exitstatus'

status: stopped + exitstatus: OK means success; anything else, read the task log (.../tasks/{upid}/log) and report it.

Gotchas

TLS: homelab nodes often use self-signed certs → set PVE_VERIFY_SSL=0 knowingly, or trust the CA.
Node-scoped paths: most operations require the correct {node} — discover it from /cluster/resources.
Version drift: field/endpoint shapes can change between 8.x and 9.x — verify against the API viewer for the running version (homelab-research).
Permissions: a 403 usually means the token lacks an ACL on that path — grant the minimal role needed.

More from this repository

same repository

dockhand

Redth/homelab-assist

Manage Docker via Dockhand — the preferred control plane in this homelab — and its Hawser remote agents. Covers the Dockhand architecture (central server + Hawser Standard/Edge agents), how to drive it (the mcp-dockhand MCP server or its REST API), compose-stack and container operations, multi-host/environment targeting, and Git-synced stacks. Load this when the user manages Docker with Dockhand.

2026-07-010

docker-compose-stacks

Redth/homelab-assist

Shared foundational knowledge for working with Docker Compose stacks — the compose file format, services/networks/volumes/secrets, environment and .env handling, healthchecks, common operations (up/down/pull/logs/ps), and safe-change practices. Load this for any compose-based work, alongside the control-plane skill (Dockhand/Portainer/Dockge) that actually applies the changes.

2026-06-290

docker-on-proxmox

Redth/homelab-assist

Understand and troubleshoot a Docker host running inside Proxmox — as a VM or as a privileged/unprivileged LXC — and how VLAN networking, macvlan/ipvlan, VLAN-aware bridges, and passed-through/bind-mounted storage interact across the Proxmox and Docker layers. Load this when a Docker networking or storage problem may originate at the Proxmox layer, or when planning how to host Docker on Proxmox.

2026-06-290

docker-overview

Redth/homelab-assist

Entry point and router for managing Docker in a homelab. Load this first for any Docker request — it identifies which control plane is in use (Dockhand preferred, or Portainer/Dockge/raw Engine), establishes the version check, and routes to the right skill (compose stacks, Dockhand, reverse-proxy label routing, or Docker-on-Proxmox networking).

2026-06-290

dockge

Redth/homelab-assist

Manage Docker compose stacks via Dockge — a file-based stack manager that stores stacks as compose files under /opt/stacks. Covers its file-on-disk model, the lack of a REST API/MCP (so operations are filesystem- or SSH-oriented), and how to edit stacks safely. Load this when the user manages Docker with Dockge.

2026-06-290

npm-reverse-proxy

Redth/homelab-assist

Set up and manage domain routing for homelab services using nginx-proxy-manager (NPM) driven by Docker container labels via npm-docker-sync. Load this when the user wants to expose a container/stack at a domain, debug why a service isn't routing, or understand the label-based proxy-host automation pattern. Covers the npm.* label scheme, how sync maps containers to NPM proxy hosts, and SSL/forced-host details.

2026-06-290

name	proxmox-api
description	How to authenticate to and call the Proxmox VE REST API — API token setup, the pve-api.sh helper, common endpoints, and how to poll background tasks. Load this when you need to make Proxmox API calls directly (any VM/LXC/storage/backup/cluster operation that goes through the API rather than an MCP server).

Proxmox VE REST API

Authentication — use API tokens

Prefer API tokens over password/ticket auth: stateless, no CSRF token needed, individually revocable, support privilege separation and expiry.

Create one (UI: Datacenter > Permissions > API Tokens, or CLI on the node):

pveum user token add automation@pve mytoken --privsep 1
# grant the token a role on a path, e.g.:
pveum acl modify / --tokens 'automation@pve!mytoken' --roles PVEVMAdmin

Header format:

Authorization: PVEAPIToken=USER@REALM!TOKENNAME=SECRET-UUID

Privilege separation (--privsep 1) means the token gets only the ACLs you grant it, independent of the user. Grant the least privilege the task needs.

The helper script

scripts/pve-api.sh wraps token auth + curl and defaults to GET. Configure via env (never hard-code): PVE_HOST, PVE_PORT, PVE_TOKEN_ID, PVE_TOKEN_SECRET, PVE_VERIFY_SSL.

scripts/pve-api.sh GET /version
scripts/pve-api.sh GET /nodes
scripts/pve-api.sh GET /nodes/pve1/qemu
scripts/pve-api.sh GET /cluster/resources | jq '.data[] | {id,type,status}'

Writes (POST/PUT/DELETE) must be approved first per homelab-safety. Only then:

scripts/pve-api.sh POST /nodes/pve1/qemu/100/status/start

Common endpoints (see reference for the full map)

Purpose	Method + path
Version	`GET /version`
Nodes	`GET /nodes` ; node status `GET /nodes/{node}/status`
All resources (VMs/CTs/storage)	`GET /cluster/resources`
List VMs	`GET /nodes/{node}/qemu`
VM status / config	`GET /nodes/{node}/qemu/{vmid}/status/current` ; `.../config`
List LXC	`GET /nodes/{node}/lxc`
Storage	`GET /nodes/{node}/storage` ; content `.../storage/{store}/content`
Tasks	`GET /nodes/{node}/tasks` ; status `.../tasks/{upid}/status`

Full list: reference/api-endpoints.md.

Background tasks (UPID)

Many write operations return a task ID (UPID) and run asynchronously. Don't assume success from the POST response — poll the task:

# the POST returns {"data":"UPID:pve1:..."} ; poll it:
scripts/pve-api.sh GET /nodes/pve1/tasks/UPID:pve1:.../status | jq '.data.status,.data.exitstatus'

status: stopped + exitstatus: OK means success; anything else, read the task log (.../tasks/{upid}/log) and report it.

Gotchas

TLS: homelab nodes often use self-signed certs → set PVE_VERIFY_SSL=0 knowingly, or trust the CA.
Node-scoped paths: most operations require the correct {node} — discover it from /cluster/resources.
Version drift: field/endpoint shapes can change between 8.x and 9.x — verify against the API viewer for the running version (homelab-research).
Permissions: a 403 usually means the token lacks an ACL on that path — grant the minimal role needed.