一键在 Manus 中运行任何 Skill

proxmox-api

星标0

分支0

更新时间2026年6月29日 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).

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

Redth

Redth/homelab-assist

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

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.

同仓库更多 Skills

同仓库

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.