[READ] Ping a VM's QEMU guest agent to check it is installed and responsive.

A non-running or absent agent yields responsive=False with an explanation rather than an error.

Args: vmid: Numeric Proxmox VM id. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Create a vzdump backup of a VM/CT to a storage. Returns task UPID.

Args: vmid: Numeric Proxmox guest id (VM or container). storage: Backup-capable storage id (see storage_list / storage_content). mode: 'snapshot' (default, no downtime), 'suspend', or 'stop'. target: Proxmox target name from config. node: Node name; omit to auto-locate the guest.

[READ] List backup archives on a storage (optionally filtered by vmid).

Args: storage: Storage id to list backups from. vmid: Optional guest id filter. target: Proxmox target name from config. node: Node name; omit to use the configured default node.

[WRITE] Restore a QEMU VM from a backup archive. HIGH RISK. Returns task UPID.

With force=True this OVERWRITES an existing VM (destructive, no undo). Restoring into a free vmid records a delete as the safe inverse. Confirm with the user before calling. Pass dry_run=True to preview: it runs the same existing-VM guard (a preview that would be refused for overwriting without force refuses too) and reports whether it would overwrite or create.

Args: vmid: Target VM id to restore into. archive: Backup volume id / archive path (see backup_list). storage: Storage to place the restored disks on. force: Overwrite vmid if it already exists (destructive). dry_run: If True, preview (runs the existing-VM guard) without restoring. target: Proxmox target name from config. node: Node name; omit to use the configured default node.

[READ] List Proxmox cluster nodes with status, cpu load, and memory.

Args: target: Proxmox target name from config; omit to use the default.

[READ] Return cluster membership + quorum status.

The type=cluster row's quorate field indicates whether the cluster currently has quorum.

Args: target: Proxmox target name from config.

[READ] Poll a Proxmox async task (clone / migrate / backup) by its UPID.

Use after a write that returned a task UPID to check completion instead of re-issuing the operation. The node is parsed from the UPID when omitted.

Args: upid: The task UPID returned by an async write tool. target: Proxmox target name from config. node: Node the task runs on; omit to parse it from the UPID.

[READ] Aggregate /cluster/resources view of VMs, nodes, and storage.

Single-call cluster-wide inventory. Use this to enumerate everything before drilling into vm_get / node_status.

Args: resource_type: Optional filter — 'vm', 'node', or 'storage'. target: Proxmox target name from config.

[READ] Detailed status for one node: cpu, load average, memory, uptime.

Args: node: Node name (see node_list). target: Proxmox target name from config.

[READ] Fetch the log lines of an async task by its UPID.

Returns {"lines": [...], "returned": N, "limit": L, "truncated": bool}. When truncated is true there are more lines than were returned — raise limit or narrow the query rather than assuming you have the whole log.

Args: upid: The task UPID. limit: Max log lines to return. target: Proxmox target name from config. node: Node the task runs on; omit to parse it from the UPID.

[READ] Return a free VMID for a new guest (/cluster/nextid).

Args: target: Proxmox target name from config.

[READ] Rank cluster nodes by CPU / memory / root-fs pressure.

Pulls the /cluster/resources node view and flags each node over the CPU (85%), memory (90%), or disk (85%) thresholds, worst-first, citing the measured percentage and a concrete action for every finding.

Args: target: Proxmox target name from config; omit to use the default.

[READ] Scan VMs and containers for stopped guests, memory saturation, and disks near full.

Pulls the /cluster/resources guest view (qemu + lxc) and reports worst-first findings plus the list of stopped guests, each finding citing the measured number and a concrete remediation.

Args: target: Proxmox target name from config; omit to use the default.

[WRITE] Grow a VM disk. GROW-ONLY — shrink requests are refused.

No undo token: growing a disk cannot be reversed. Pass dry_run=True to preview.

Args: vmid: Numeric Proxmox VM id. disk: Disk key, e.g. 'scsi0', 'virtio0', 'sata0'. size: '+G' increment (e.g. '+10G') or a larger absolute size. dry_run: If True, preview without resizing. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Move a VM disk to another storage. Returns task UPID. Async.

Records a reverse move as the undo token when the source storage is known. Pass dry_run=True to read the disk's current placement and preview the move.

Args: vmid: Numeric Proxmox VM id. disk: Disk key, e.g. 'scsi0'. storage: Destination storage id. delete: Remove the source copy after the move completes. dry_run: If True, preview the from→to move without moving anything. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[READ] List the firewall rules attached to a VM.

Args: vmid: Numeric Proxmox VM id. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[READ] Cluster-wide firewall options (notably whether it is enabled).

Args: target: Proxmox target name from config.

[READ] Current HA status entries, or a not-configured signal.

Returns {"configured": bool, "entries": [...]}; when HA is absent the list is empty and a message explains it.

Args: target: Proxmox target name from config.

[READ] HA-managed resources (VMs/CTs); empty when HA is not configured.

Args: target: Proxmox target name from config.

[READ] List LXC containers with name, vmid, status, cpu, mem.

Args: target: Proxmox target name from config; omit to use the default. node: Node name; omit to use the configured default / all nodes.

[WRITE] Start an LXC container. Returns the task UPID. Inverse: ct_stop.

Pass dry_run=True to preview.

Args: vmid: Numeric container id (see ct_list). dry_run: If True, preview without starting. target: Proxmox target name from config. node: Node name; omit to auto-locate the container.

[WRITE] Stop an LXC container. Returns the task UPID. Inverse: ct_start.

Pass dry_run=True to preview.

Args: vmid: Numeric container id (see ct_list). dry_run: If True, preview without stopping. target: Proxmox target name from config. node: Node name; omit to auto-locate the container.

[READ] List resource pools (poolid + comment).

Args: target: Proxmox target name from config.

[READ] List the members of a pool (VMs, CTs, storage).

Args: poolid: Pool id (see pool_list). target: Proxmox target name from config.

[READ] List storage pools on a node (id, type, total/used/avail bytes).

Args: target: Proxmox target name from config; omit to use the default. node: Node name; omit to use the target's configured default node.

[READ] List volumes on a storage pool (ISOs, disk images, backups, templates).

Args: storage: Storage pool id (see storage_list). content: Optional filter — 'iso', 'images', 'backup', 'vztmpl'. target: Proxmox target name from config. node: Node name; omit to use the configured default node.

[READ] List recorded, not-yet-applied undo tokens (most recent first).

Each entry names the original tool, the inverse tool that undo_apply would run, and a human note. Use the undoId with undo_apply.

Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra row is fetched), not guessed from a length coincidence: when it is true there are MORE tokens than shown, so re-run with a higher limit rather than reporting the list as complete.

Each entry carries effectVerified. False means the original write lost its response, so the change it reverses is PROBABLE, not confirmed — check the live state before applying, and do not report the result as a restore of a state that may never have been reached.

Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.

[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.

The inverse runs through its own governed tool, so its own risk tier is recorded on the audit row there. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.

Args: undo_id: The undoId from undo_list (or an _undo_id in a write result). dry_run: If True, preview the inverse tool + params without running it. target: Passed through to the inverse tool when it accepts a target.

[READ] List QEMU VMs with name, vmid, status, cpu, mem.

Scans the given node, the configured default node, or all cluster nodes. Use vm_get for full status of a single VM.

Args: target: Proxmox target name from config; omit to use the default. node: Node name; omit to use the target's configured node / all nodes.

[READ] Return current status detail for a single VM by vmid.

Args: vmid: Numeric Proxmox VM id (see vm_list). target: Proxmox target name from config. node: Node name; omit to auto-locate the VM across nodes.

[WRITE] Start a VM. Returns the Proxmox task UPID. Inverse: vm_stop.

Args: vmid: Numeric Proxmox VM id. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Hard-stop (power off) a VM. Returns the task UPID. Inverse: vm_start.

This is an immediate power-off (not a graceful guest shutdown); the guest filesystem may be left dirty. Audited to ~/.proxmox-aiops/audit.db. Pass dry_run=True to preview.

Args: vmid: Numeric Proxmox VM id. dry_run: If True, preview without stopping. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Create a named snapshot of a VM. Inverse: vm_snapshot_delete.

Pass dry_run=True to preview.

Args: vmid: Numeric Proxmox VM id. name: Snapshot name (must be unique for the VM). dry_run: If True, preview without creating. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Delete a named snapshot from a VM. Destroys a rollback point — no undo.

Pass dry_run=True to preview.

Args: vmid: Numeric Proxmox VM id. name: Snapshot name to delete (see vm_snapshot_list). dry_run: If True, preview without deleting. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[READ] List snapshots for a VM (name + description).

Args: vmid: Numeric Proxmox VM id. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[READ] Return a VM's config (cores, memory, ostype, boot order).

Args: vmid: Numeric Proxmox VM id. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Graceful ACPI shutdown of a VM (vs the hard vm_stop). Inverse: vm_start.

Pass dry_run=True to preview.

Args: vmid: Numeric Proxmox VM id. dry_run: If True, preview without shutting down. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Reboot a VM (graceful). No undo token — reboot has no inverse.

Args: vmid: Numeric Proxmox VM id. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Change a VM's cores and/or memory (MiB). Inverse: restore prior values.

Provide at least one of cores / memory. The previous values are captured so the harness records a reverse reconfigure as the undo token. Pass dry_run=True to read the current cores/memory and preview the change.

Args: vmid: Numeric Proxmox VM id. cores: New vCPU core count (omit to leave unchanged). memory: New memory in MiB (omit to leave unchanged). dry_run: If True, preview what would change without applying it. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Clone a VM to a new vmid. Returns the task UPID. Inverse: vm_delete(newid).

Cloning is asynchronous — poll completion with task_status, do not re-issue. Pass dry_run=True to preview.

Args: vmid: Source VM id to clone from. newid: New (unused) VM id for the clone. name: Optional name for the clone. dry_run: If True, preview without cloning. target: Proxmox target name from config. node: Node name; omit to auto-locate the source VM.

[WRITE] Permanently destroy a VM. IRREVERSIBLE — no undo token.

Confirm with the user before calling. Audited to ~/.proxmox-aiops/audit.db. Pass dry_run=True to preview.

Args: vmid: Numeric Proxmox VM id to destroy. dry_run: If True, preview without destroying. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.

[WRITE] Migrate a VM to another node. Returns task UPID. Inverse: migrate back.

Asynchronous — poll completion with task_status. Pass dry_run=True to preview.

Args: vmid: Numeric Proxmox VM id. target_node: Destination node name. online: True (default) for live migration; False to migrate while stopped. dry_run: If True, preview without migrating. target: Proxmox target name from config. node: Source node name; omit to auto-locate the VM.

[WRITE] Roll a VM back to a snapshot. IRREVERSIBLE — discards changes since then.

No undo token (the discarded state cannot be recovered). Confirm with the user. Pass dry_run=True to preview.

Args: vmid: Numeric Proxmox VM id. name: Snapshot name to roll back to (see vm_list_snapshots). dry_run: If True, preview without rolling back. target: Proxmox target name from config. node: Node name; omit to auto-locate the VM.