Proxmox VE

Use the local Proxmox CLI first. Prefer read-only inspection before any mutating action, and confirm before stopping guests, rolling back snapshots, or changing configuration.

Safe workflow

1. Verify the environment and auth context.
2. Discover nodes and guests with read-only commands.
3. Check current state before proposing an action.
4. Perform the smallest requested mutation.
5. Re-check status and report what changed.

Start with lightweight inspection:

pveversion
hostname
pvesh get /version
pvesh get /nodes
pvesh get /cluster/status

If the user did not specify a node, discover it first instead of guessing.

Read-first inspection

List nodes:

pvesh get /nodes

List QEMU VMs on a node:

pvesh get /nodes/<node>/qemu
qm list

List LXC containers on a node:

pvesh get /nodes/<node>/lxc
pct list

Inspect a specific VM or container:

qm status <vmid>
qm config <vmid>
pct status <vmid>
pct config <vmid>

If the user only gives a VMID and not the guest type, identify it first instead of guessing:

qm list
pct list
pvesh get /cluster/resources --type vm

Useful cluster and node checks:

pvesh get /cluster/resources
pvesh get /nodes/<node>/status
pvesh get /nodes/<node>/tasks --limit 10

Prefer JSON when the output will be parsed or compared:

pvesh get /nodes --output-format json
pvesh get /nodes/<node>/qemu --output-format json

Guest lifecycle actions

Check state first, then act.

Recommended sequence:

1. Identify the node and guest type.
2. Check current guest status.
3. Confirm the exact action if it is disruptive.
4. Run the smallest matching command.
5. Re-check status and report the result.

QEMU VM actions:

qm start <vmid>
qm stop <vmid>
qm shutdown <vmid>
qm reboot <vmid>
qm reset <vmid>

LXC container actions:

pct start <vmid>
pct stop <vmid>
pct shutdown <vmid>
pct reboot <vmid>

Guidance:

• Prefer shutdown/reboot for graceful operations.
• Use stop only when the user explicitly wants a forced stop or graceful shutdown is not working.
• Mention whether the target is a QEMU VM (qm) or LXC container (pct) before running the command.

Snapshot workflow

Inspect snapshots before creating, deleting, or rolling back.

QEMU snapshots:

qm listsnapshot <vmid>
qm snapshot <vmid> <snapshot-name>
qm delsnapshot <vmid> <snapshot-name>
qm rollback <vmid> <snapshot-name>

LXC snapshots:

pct listsnapshot <vmid>
pct snapshot <vmid> <snapshot-name>
pct delsnapshot <vmid> <snapshot-name>
pct rollback <vmid> <snapshot-name>

Rules:

• Confirm before rollback or delsnapshot.
• Use clear, generic snapshot names in examples such as pre-update or before-maintenance.
• Report post-action status after snapshot operations.

API-style access with pvesh

Use pvesh when the user asks for API-like inspection or when you need structured output without hand-building HTTP requests.

Examples:

pvesh get /cluster/resources
pvesh get /nodes/<node>/qemu/<vmid>/status/current
pvesh get /nodes/<node>/lxc/<vmid>/status/current

Use pvesh usage <path> to discover parameters for less common endpoints:

pvesh usage /nodes/<node>/qemu/<vmid>/status/current -v

Read references/commands-and-auth.md when the task needs API token guidance, remote API examples, or a broader command map.

Bundled scripts

Use the bundled Python helpers when the user wants reusable code or a minimal scriptable PVE API client.

Scripts:

• scripts/pve_api.py — generic GET/POST helper for API paths
• scripts/list_nodes.py — list nodes
• scripts/list_guests.py <node> [--kind qemu|lxc|all] — list guests on a node
• scripts/guest_status.py <node> <qemu|lxc> <vmid> — fetch current status

Expected environment variables:

export PVE_HOST='proxmox.example.com'
export PVE_USER='automation@pam'
export PVE_TOKEN_ID='automation'
export PVE_TOKEN_SECRET='replace-me'

Example usage:

python3 {baseDir}/scripts/list_nodes.py
python3 {baseDir}/scripts/list_guests.py pve-node-1 --kind all
python3 {baseDir}/scripts/guest_status.py pve-node-1 qemu 100
python3 {baseDir}/scripts/pve_api.py /cluster/resources

Auth and environment guidance

On a Proxmox host, local CLI access is often enough:

whoami
pveversion
pvesh get /version

For remote API usage, prefer environment variables over hardcoding secrets:

export PVE_HOST='proxmox.example.com'
export PVE_USER='automation@pam'
export PVE_REALM='pam'
export PVE_TOKEN_ID='automation'
export PVE_TOKEN_SECRET='replace-me'

Do not print or paste real secrets back into chat. If credentials are missing, ask for them or ask the user to authenticate locally.

Guardrails

• Do not assume VMID ownership or guest purpose from the numeric ID alone.
• Do not reboot, stop, reset, roll back, or delete without explicit user intent.
• Prefer node and guest discovery commands before suggesting actions.
• After any mutation, run a status check and summarize the result.
• If the task expands into storage, networking, clustering changes, or backup jobs, inspect first and ask before editing.