pmox¶

A command-line tool for exploring and managing a Proxmox VE cluster, built so an AI agent can drive it safely.

pmox wraps the Proxmox API with concise commands, pretty tables for humans, and JSON for machines.

Read-only by default

Nothing changes without --dangerous, and nothing is destroyed without --dangerous and --yes. The two gates are independent, and neither can be enabled from a .env file. See Safety model.

pmox demo

pip install pmox

Quick start

Install, create an API token, and go from nothing to an SSH-able VM in one command.

Get started
Safety model

The two gates, the exit codes, and the JSON error envelopes that make the tool safe to hand to an agent.

How the gates work
Command reference

Every command, the global flags, and the conventions that let you skip --node almost everywhere.

All commands
Provisioning

Cloud-init VMs, LXC containers, and the agent golden templates that make DHCP addresses reliable.

Provisioning guide
Configuration

TOML file, environment variables, and flags — and the precedence order between them.

Configure pmox
Using with an agent

Why the JSON envelopes exist, and the Claude Code plugin that teaches the safety rules.

Agent setup

What it looks like¶

Output auto-detects its destination: tables at a terminal, JSON when captured or piped. Force either way with --json / --no-json.

At a terminalCaptured by an agent

$ pmox vm ip 113 --wait
VM 113 (web) on lukeserver · primary 192.168.0.140
┌───────────┬───────────────┬──────┐
│ Interface │ IPv4          │ IPv6 │
├───────────┼───────────────┼──────┤
│ eth0      │ 192.168.0.140 │ -    │
└───────────┴───────────────┴──────┘

{
  "vmid": 113,
  "node": "lukeserver",
  "kind": "qemu",
  "name": "web",
  "source": "guest-agent",
  "primary": "192.168.0.140",
  "interfaces": [
    {
      "name": "eth0",
      "mac": "bc:24:11:aa:bb:cc",
      "addresses": [
        {"family": "ipv4", "address": "192.168.0.140", "prefix": 24, "scope": "global"}
      ]
    }
  ]
}

The source field says where the answer came from — guest-agent, the static cloud-init config, or a same-LAN arp scan.

Why not `qm` or `pvesh`¶

Both need a root shell on a node. pmox needs a scoped API token and runs from any machine on your network — your laptop, a CI runner, or an agent's sandbox. And unlike a raw API wrapper, it refuses to mutate anything until you say so twice.

pmox¶

What it looks like¶

Why not qm or pvesh¶

Why not `qm` or `pvesh`¶