Proxmox (pmox)

pmox

A friendly, AI-friendly command-line tool to explore and manage a Proxmox VE cluster.

pmox wraps the Proxmox API with clean commands, pretty tables for humans, and a --json mode for machines. It is read-only by default so you (or an AI) can explore safely, with two layers of protection before anything can change.

pmox nodes list
pmox vm list
pmox vm status 100
pmox --dangerous vm start 100
pmox --dangerous vm delete 100 --yes

Safety model

Two independent gates protect your cluster:

Gate	Flag	Applies to	Default
Dangerous mode	--dangerous (or PMOX_DANGEROUS=1)	any state change (power, create, delete, clone, migrate, snapshot)	off — read-only
Confirmation	--yes	destructive ops: delete, stop, reset, migrate, rollback	required when non-interactive

So:

• Explore with no flags — nothing can be modified.
• Change something benign (e.g. start) — add --dangerous.
• Destroy something (e.g. delete) — add --dangerous and --yes.

When running non-interactively (e.g. an AI calling the CLI), a destructive op without --yes is refused rather than silently prompted. Exit codes: 0 ok · 1 error · 2 config · 3 confirmation required · 4 read-only.

Install

cd pmox
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -e .

This puts a pmox command on your PATH. You can also run it without installing via python -m pmox.

Configure

Create an API token in Proxmox: Datacenter → Permissions → API Tokens. For full management, give the token the privileges it needs (or, for a homelab, uncheck "Privilege Separation" so it inherits the user's permissions).

Provide configuration via environment variables, a .env file, a TOML config file, or CLI flags (highest priority last):

.env (copy from .env.example):

PROXMOX_HOST=192.168.1.10
PROXMOX_TOKEN_ID=root@pam!pmox
PROXMOX_TOKEN_SECRET=00000000-0000-0000-0000-000000000000
PROXMOX_VERIFY_SSL=false

TOML at ~/.config/pmox/config.toml (or point --config / PMOX_CONFIG at one):

host = "192.168.1.10"
token_id = "root@pam!pmox"
token_secret = "..."
verify_ssl = false

TLS verification defaults to off because homelab Proxmox uses self-signed certificates. Set PROXMOX_VERIFY_SSL=true (or --verify-ssl) if your node has a CA-signed cert.

Commands

pmox version                      Proxmox version of the connected node
pmox nodes list                   nodes + CPU/mem/uptime
pmox nodes status <node>          detailed node status
pmox cluster status               cluster membership/quorum
pmox cluster resources [--type]   everything the cluster sees (vm|node|storage|...)

pmox vm list [--node N]           QEMU VMs (cluster-wide)
pmox vm status <vmid>             live status (node auto-resolved)
pmox vm config <vmid>             configuration
pmox vm start|shutdown|reboot|suspend|resume <vmid>      (needs --dangerous)
pmox vm stop|reset <vmid>                                (needs --dangerous --yes)
pmox vm create <vmid> --node N [--name X] [-o key=value ...]
pmox vm clone <vmid> --newid <id> [--name X] [--full] [--target N]
pmox vm migrate <vmid> --target N [--online]            (needs --dangerous --yes)
pmox vm delete <vmid> [--purge]                          (needs --dangerous --yes)
pmox vm snapshot list|create|delete|rollback <vmid> ...

pmox ct ...                       same as `vm`, for LXC containers
pmox storage list [--node N]      storage usage
pmox storage content <id> --node N
pmox task list --node N           recent tasks
pmox task status|log <upid> --node N

--node is optional for guest commands — pmox finds which node a VMID lives on via the cluster resources endpoint.

Using with an AI (e.g. Claude)

Point the AI at the CLI and let it run commands via the shell. Recommended:

• Set PMOX_JSON=1 so every command returns structured JSON the model can parse.
• Leave dangerous mode off for exploration. The AI literally cannot change anything without you adding --dangerous (and --yes for destructive ops), so accidental damage is impossible during read-only investigation.

export PMOX_JSON=1
pmox cluster resources           # AI explores freely, read-only
pmox vm status 100

When you want the AI to act, tell it to include the flags explicitly:

pmox --dangerous vm start 100
pmox --dangerous vm snapshot create 100 before-upgrade

Claude Code plugin

This repo is also a Claude Code plugin (in plugin/), so Claude can drive pmox for you with the safety gates intact:

/plugin marketplace add C:\Users\Luke\Workspace\pmox
/plugin install pmox@pmox-marketplace