pve_agent_exec
Run commands inside QEMU guests via qemu-agent, with dry-run planning. Confirm to execute and poll for exit status.
Instructions
MUTATION: run a command inside a guest via the qemu-agent (async, polls for result).
Dry-run by default: without confirm=True you get a PLAN recorded to the ledger. Re-call with confirm=True to execute.
Requires PROXIMO_ENABLE_AGENT=1 and the VMID in PROXIMO_AGENT_ALLOWLIST. The command runs INSIDE the guest OS — no undo primitive on this plane.
Returns status="ok" only when the agent reports the process exited. Returns status="running" with pid when the poll deadline is reached before exit.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | PVE node the guest runs on; omit to resolve automatically. | |
| vmid | Yes | Numeric VMID of the target QEMU guest (allowlist-scoped). | |
| command | Yes | Argv list to run in the guest via the qemu-agent. | |
| confirm | No | False (default) returns a dry-run PLAN; true executes. | |
| timeout | No | Seconds to poll for exit before returning status='running'. | |
| proximo_target | No | Which configured Proxmox target to run this call against — a target name from your multi-target config (a specific PVE/PBS/PMG/PDM box). Omit to use the single/default target from the environment; the selection applies only to this call. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |