pve_* — Proxmox Virtual Environment

The Proxmox tool namespace — listing and inspecting nodes/storage/templates, LXC and VM lifecycle, in-guest command execution, and async task tracking.

The pve_* family manages the Proxmox host (pve) that runs nearly every SuperHiTech VM and container — leif, nvrbackup, shtops, obs-01, webserver, FreePBX. Most tools take a node (the Proxmox node name, almost always pve) and a vmid. Lifecycle operations are asynchronous: they return a task UPID you poll with pve_task_status. See Proxmox for the host.

Inventory & status

pve_node_status

pve_node_status()

CPU, memory, disk, uptime, and load per Proxmox node. No args.

pve_lxc_list / pve_vm_list

pve_lxc_list(node=None)
pve_vm_list(node=None)

List LXC containers / QEMU VMs with vmid, name, status, and resource usage. Omit node to include all nodes.

pve_storage_list

pve_storage_list(node=None)

Storage pools with type, used/total/available, and content types.

pve_template_list

pve_template_list(node, storage="local")

Available LXC templates on a node/storage. Use this to find the exact template name before pve_lxc_create — the create call needs the precise ostemplate string.

LXC lifecycle

pve_lxc_create

pve_lxc_create(node, vmid, hostname, ostemplate, storage, rootfs_size_gb,
               cores, memory_mb, swap_mb=512, password=None,
               ssh_public_keys=None, net0="name=eth0,bridge=vmbr0,ip=dhcp",
               unprivileged=1, features=None, start=False)

Required: node, vmid, hostname, ostemplate, storage, rootfs_size_gb, cores, memory_mb. Returns the async task UPID.

pve_lxc_start / pve_lxc_shutdown / pve_lxc_stop / pve_lxc_destroy

pve_lxc_start(node, vmid)
pve_lxc_shutdown(node, vmid)              # graceful
pve_lxc_stop(node, vmid, force=False)     # hard power-off — force=True required
pve_lxc_destroy(node, vmid, force=False)  # permanent delete — force=True required

shutdown is graceful; stop is an abrupt power-off and requires force=True. destroy permanently deletes the container and also requires force=True. Each returns a task UPID (poll with pve_task_status).

pve_lxc_exec

pve_lxc_exec(node, vmid, command)

Run a command inside an LXC via pct exec over SSH to the Proxmox host. Returns stdout, stderr, return_code.

VM operations

pve_vm_exec

pve_vm_exec(node, vmid, command)

Run a command inside a QEMU VM via the QEMU Guest Agent. Requires qemu-guest-agent running in the guest and agent: 1 in the VM config. If the agent is unavailable, return_code is non-zero and stderr carries the host-side error.

Async tasks

pve_task_status

pve_task_status(node, upid)

Poll the status of any async operation (create/start/stop/destroy) by the UPID it returned. The lifecycle tools don’t block — this is how you confirm they finished.

  • Proxmox — the node, storage pools, and the guests it hosts
  • obs-01 — reached via pve_lxc_exec (CT 111), the Docker-in-LXC case
  • Shell & file tools — host-scoped shell families for guests that have one