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. 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:

CODEBLOCK0

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

Read-first inspection

List nodes:

CODEBLOCK1

List QEMU VMs on a node:

CODEBLOCK2

List LXC containers on a node:

CODEBLOCK3

Inspect a specific VM or container:

CODEBLOCK4

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

CODEBLOCK5

Useful cluster and node checks:

CODEBLOCK6

Prefer JSON when the output will be parsed or compared:

CODEBLOCK7

Guest lifecycle actions

Check state first, then act.

Recommended sequence:

1. 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:

CODEBLOCK8

LXC container actions:

CODEBLOCK9

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:

CODEBLOCK10

LXC snapshots:

CODEBLOCK11

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:

CODEBLOCK12

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

CODEBLOCK13

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
• INLINECODE14 — list nodes
• INLINECODE15 — list guests on a node
• INLINECODE16 — fetch current status

Expected environment variables:

CODEBLOCK14

Example usage:

CODEBLOCK15

Auth and environment guidance

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

CODEBLOCK16

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

CODEBLOCK17

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.