Querying Proxmox: VMs, LXCs, and Cluster Status

Two Ways to Talk to Proxmox

Proxmox VE exposes its management surface two ways, and your Hermes agent can use both:

1. The pvesh CLI -- a command-line wrapper for the Proxmox REST API, available on any Proxmox node. If your agent has SSH access to the Proxmox node, it can call pvesh directly.
2. The REST API directly -- Proxmox runs an API server on port 8006 (https://proxmox-host:8006/api2/json). Your agent can query this with curl if it has an API token.

For most homelab setups, SSH + pvesh is the simpler path. You avoid token management, and the queries are easier to read and iterate on. The REST API is worth learning once you want to automate actions (starting or stopping VMs) or query from a machine that does not have SSH access to the Proxmox node.

Listing VMs and LXCs with pvesh

With the SSH terminal backend pointed at your Proxmox node (or using a profile configured for it), ask your agent:

> list all running VMs and LXC containers on this Proxmox node

The agent will run commands like these:

# All VMs (KVM)
qm list

# All LXC containers
pct list

# Or query via pvesh for richer output
pvesh get /nodes/pve/qemu --output-format json
pvesh get /nodes/pve/lxc --output-format json

Replace pve with your actual node name (visible in the Proxmox web UI). The agent can read the JSON output and summarize it: which VMs are running vs stopped, their memory and CPU allocation, uptime.

Checking Node Resources

To see how much CPU and memory a node is actually using:

pvesh get /nodes/pve/status --output-format json

The response includes cpu (fractional usage, 0-1), memory.used and memory.total (in bytes), and uptime (in seconds). Ask your agent to convert these to human-readable form and tell you if anything is overloaded.

For a multi-node cluster, get cluster-wide visibility with:

pvesh get /cluster/resources --output-format json

This returns every node, VM, LXC, and storage pool in the cluster with their current state. It is the single best command for a snapshot of your entire Proxmox environment.

Querying Storage Pools

To check storage pool usage (local-lvm, NFS mounts, ZFS datasets presented to Proxmox):

pvesh get /nodes/pve/storage --output-format json

Or for a specific pool:

pvesh get /nodes/pve/storage/local-lvm/status --output-format json

The agent can parse the used, avail, and total fields and flag pools that are above a threshold you care about (say, 80% full).

Using the REST API with a Token

If you prefer querying from outside the Proxmox node (for example, from your Hermes VM with the local backend), create an API token in the Proxmox web UI under Datacenter → Permissions → API Tokens. Then:

curl -k 
  -H "Authorization: PVEAPIToken=USER@REALM!TOKENID=TOKEN-SECRET" 
  "https://192.168.1.10:8006/api2/json/nodes"

The -k flag skips TLS certificate verification (fine for homelab self-signed certs). Store the token secret in ~/.hermes/.env as PROXMOX_TOKEN and reference it via terminal.env_passthrough in config.yaml:

terminal:
  env_passthrough:
    - PROXMOX_TOKEN

Then your agent can use $PROXMOX_TOKEN in curl commands without the secret being hardcoded in any file the agent can read.

Putting It Together: A Cluster Summary

Once the SSH backend is working, try this conversation with your agent:

> give me a summary of the Proxmox cluster: which nodes are up,
  how many VMs and LXCs are running vs stopped,
  which storage pools are getting full, and any errors worth knowing about

The agent will chain together several pvesh commands, interpret the JSON output, and write you a plain-English summary. This is the qualitative leap over shell scripts: you asked a question in natural language and got an answer in natural language, without writing a parser.

A Note on Permissions

The Hermes user on your Proxmox node needs sufficient permissions to run qm list, pct list, and pvesh get queries. The PVEAuditor role in Proxmox provides read-only access across the cluster without allowing any destructive operations. Assign it at the datacenter level:

Datacenter → Permissions → Add → User Permission → User: hermes@pam, Role: PVEAuditor, Path: /

Read-only is sufficient for everything in this lesson. Lesson 8 covers the broader principle of why you want read-only for the agent by default.