@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_snapshot.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_snapshot",
+  "usageNotes": "Creates a point-in-time snapshot of an LXC container; the container does not need to be stopped first, though a running container snapshot may have inconsistent filesystem state unless the application inside is quiesced. Returns a UPID string — poll the task API to confirm completion before relying on the snapshot. Requires the VM.Snapshot privilege on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Snapshot a running web-server container before a package upgrade",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 201
+      },
+      "params": {
+        "snapname": "preupgrade20260629",
+        "description": "Pre-upgrade snapshot before apt dist-upgrade 2026-06-29"
+      }
+    }
+  ],
+  "tips": [
+    "snapname must follow pve-configid format: alphanumeric plus hyphens/underscores, max 40 chars — no spaces or dots.",
+    "Snapshots of running containers capture RAM state implicitly via the container's filesystem, but they are NOT crash-consistent; quiesce or stop the container for a clean backup.",
+    "Poll GET /nodes/{node}/tasks/{upid}/status to wait for the snapshot task to finish before triggering any dependent operation (rollback, clone, etc.).",
+    "LXC snapshots require the storage backend to support snapshots (e.g., ZFS, LVM-thin, or Ceph); plain directory storage will fail at snapshot time."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_snapshot",
+    "post_nodes_node_lxc_vmid_snapshot_snapname_rollback",
+    "delete_nodes_node_lxc_vmid_snapshot_snapname",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_snapshot_snapname_rollback.json

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_snapshot_snapname_rollback",
+  "usageNotes": "Rolls back an LXC container's disk and configuration to the state captured in the named snapshot; the container must be stopped before rollback unless the snapshot itself includes RAM state. Returns a UPID task string — poll the node's task log to confirm completion before treating the rollback as done. Requires either VM.Snapshot or VM.Snapshot.Rollback privilege on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Roll back container 112 to snapshot 'pre-upgrade' and start it automatically after",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 112,
+        "snapname": "pre-upgrade"
+      },
+      "params": {
+        "start": true
+      }
+    }
+  ],
+  "destructiveReason": "All disk and configuration changes made after the snapshot was taken are permanently discarded and cannot be recovered once the rollback completes.",
+  "tips": [
+    "Stop the container before rolling back if the snapshot does not include RAM state; a running container rollback may fail or corrupt state.",
+    "Use 'start': true to avoid a separate start call after rollback — useful in automated recovery scripts.",
+    "Take a safety snapshot of the current state before rolling back if there is any chance you need to preserve recent changes.",
+    "The returned UPID should be polled via GET /nodes/{node}/tasks/{upid}/status to confirm the task succeeded before proceeding."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_snapshot",
+    "get_nodes_node_lxc_vmid_snapshot",
+    "get_nodes_node_lxc_vmid_snapshot_snapname_config",
+    "delete_nodes_node_lxc_vmid_snapshot_snapname",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_spiceproxy.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_spiceproxy",
+  "usageNotes": "Use this to obtain a SPICE connection ticket for a running LXC container; the returned object (host, tls-port, password, proxy, type) can be passed directly to 'remote-viewer' or a compatible SPICE client. The container must be running and the target node must be online; the caller requires the VM.Console privilege on /vms/{vmid}. The optional 'proxy' parameter should be set to the hostname or IP the client will use to reach the SPICE proxy — omit it to default to the node where the container is currently running.",
+  "examples": [
+    {
+      "summary": "Get SPICE config for LXC 200 on node pve1, with proxy hint matching the API host",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200
+      },
+      "params": {
+        "proxy": "pve1.nightsquawk.tech"
+      }
+    }
+  ],
+  "tips": [
+    "Pass the full response object directly to 'remote-viewer' via a .vv file or stdin — no manual field mapping needed.",
+    "If the SPICE window never opens, confirm the container has a console device configured (e.g. lxc.console.size set or Proxmox default tty); pure network-only containers may not expose a usable console.",
+    "The password in the response is a short-lived one-time token; request a fresh proxy config each time a session is opened rather than caching it.",
+    "All cluster nodes run spiceproxy on port 3128 by default — set 'proxy' to whichever node is reachable from the client's network segment."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_status_current",
+    "post_nodes_node_lxc_vmid_status_start",
+    "post_nodes_node_lxc_vmid_vncproxy"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_status_reboot.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_status_reboot",
+  "usageNotes": "Use this to apply pending container configuration changes (e.g. CPU, memory, network edits) without a full stop/start cycle; Proxmox performs a clean shutdown then immediately starts the container again. The container must be in a running state and the target node must be online; calling this on a stopped container will fail. Returns a task UPID string — poll the node's task log to confirm completion.",
+  "examples": [
+    {
+      "summary": "Reboot LXC container 110 on node pve1 with a 60-second shutdown timeout",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {
+        "timeout": 60
+      }
+    }
+  ],
+  "destructiveReason": "Rebooting the container interrupts all running services inside it for the duration of the shutdown and startup cycle.",
+  "tips": [
+    "If timeout is omitted, Proxmox uses its default shutdown timeout (typically 60 s); set an explicit value for containers with slow-stopping services.",
+    "The returned UPID can be passed to GET /nodes/{node}/tasks/{upid}/status to monitor reboot progress.",
+    "Pending config changes saved via PUT /nodes/{node}/lxc/{vmid}/config are applied automatically during the reboot without needing a separate commit step."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_status_shutdown",
+    "post_nodes_node_lxc_vmid_status_start",
+    "post_nodes_node_lxc_vmid_status_stop",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_status_resume.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_status_resume",
+  "usageNotes": "Use this to resume a suspended LXC container; the container must already be in a suspended state (not stopped or running). The call returns a task UPID string that can be polled via the tasks API to confirm completion. The caller must hold the VM.PowerMgmt privilege on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Resume a suspended LXC container (vmid 201) on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Check container status first with GET /nodes/{node}/lxc/{vmid}/status/current — resuming a non-suspended container will fail.",
+    "The returned string is a UPID; poll GET /nodes/{node}/tasks/{upid}/status to confirm the resume completed successfully.",
+    "LXC resume is near-instant; if the task lingers, check whether the container's rootfs storage is accessible on the node."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_status_suspend",
+    "post_nodes_node_lxc_vmid_status_start",
+    "post_nodes_node_lxc_vmid_status_stop",
+    "get_nodes_node_lxc_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_status_shutdown.json

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_status_shutdown",
+  "usageNotes": "Sends a clean ACPI shutdown signal to a running LXC container and returns a task UPID for async tracking; the container must be in a running state on the specified node. Use `forceStop: true` to guarantee the container stops if the guest does not respond within the timeout window — omitting it on an unresponsive container will leave it running after the timeout expires. Requires the `VM.PowerMgmt` privilege on `/vms/{vmid}`.",
+  "examples": [
+    {
+      "summary": "Graceful shutdown of container 101 with a 90-second timeout and forced stop fallback",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {
+        "timeout": 90,
+        "forceStop": true
+      }
+    }
+  ],
+  "destructiveReason": "Stops the container, interrupting all running processes and making its services unavailable until it is started again.",
+  "tips": [
+    "Poll the returned UPID via GET /nodes/{node}/tasks/{upid}/status to confirm the shutdown completed before taking dependent actions.",
+    "The default timeout of 60 seconds is often too short for containers running databases or heavy workloads — increase it when services need a graceful drain.",
+    "Prefer this endpoint over the stop endpoint for production containers; stop is a hard kill, whereas shutdown allows the init system to run teardown hooks.",
+    "If the container is already stopped, the API returns an error — check status first with GET /nodes/{node}/lxc/{vmid}/status/current."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_status_stop",
+    "post_nodes_node_lxc_vmid_status_start",
+    "post_nodes_node_lxc_vmid_status_reboot",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_status_start.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_status_start",
+  "usageNotes": "Starts a stopped or suspended LXC container on the specified node. Returns a task UPID string — poll the task status endpoint to confirm the container reached the running state before issuing dependent operations. The caller must hold VM.PowerMgmt on /vms/{vmid} and the target node must be online and have the container's rootfs storage accessible.",
+  "examples": [
+    {
+      "summary": "Start container 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned UPID can be tracked via GET /nodes/{node}/tasks/{upid}/status to detect startup errors (e.g. missing network bridge, storage offline).",
+    "Use debug: true only for troubleshooting startup failures — it floods the container log and should not be left enabled in production.",
+    "skiplock bypasses any administrative lock set on the container (e.g. backup lock); only root may use it, and doing so during an active backup can corrupt the snapshot."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_status_stop",
+    "post_nodes_node_lxc_vmid_status_shutdown",
+    "post_nodes_node_lxc_vmid_status_reboot",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_status_stop.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_status_stop",
+  "usageNotes": "Immediately kills all processes in the container without a graceful shutdown — equivalent to pulling the power cord. Use only when the container is hung and unresponsive to a shutdown request, or when speed is more important than data integrity. Returns a task UPID; poll the task status to confirm the container reaches the 'stopped' state. Caller must hold VM.PowerMgmt on /vms/{vmid}.",
+  "destructiveReason": "All processes in the container are killed instantly with no opportunity to flush buffers or run shutdown hooks, which can corrupt open files and databases.",
+  "examples": [
+    {
+      "summary": "Force-stop an unresponsive LXC container (vmid 201) on node pve1, aborting any pending vzshutdown task first",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {
+        "overrule-shutdown": true
+      }
+    }
+  ],
+  "tips": [
+    "Prefer post_nodes_node_lxc_vmid_status_shutdown for a clean stop; use this only when shutdown is stuck or unresponsive.",
+    "Set overrule-shutdown: true when a vzshutdown task is already queued — otherwise the stop may be blocked.",
+    "skiplock: true requires root and should be reserved for recovery scenarios where an administrative lock is orphaned."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_status_shutdown",
+    "post_nodes_node_lxc_vmid_status_start",
+    "post_nodes_node_lxc_vmid_status_reboot",
+    "get_nodes_node_lxc_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_status_suspend.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_status_suspend",
+  "usageNotes": "Suspends a running LXC container by freezing all its processes; the container remains in memory but is unresponsive until resumed. This feature is marked experimental by Proxmox and may not behave correctly for all workloads — prefer stopping the container for predictable results. The call returns a task UPID string; poll the node task API to confirm completion before assuming the container is suspended.",
+  "examples": [
+    {
+      "summary": "Suspend LXC container 201 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Suspends all processes in the container, immediately interrupting any active workloads or network services until the container is explicitly resumed.",
+  "tips": [
+    "This endpoint has no body parameters — POST with an empty body or no body.",
+    "Use post_nodes_node_lxc_vmid_status_resume to bring the container back online after suspension.",
+    "Because suspend is experimental in LXC, test on non-critical containers first; some unprivileged containers or those using certain cgroup features may freeze incorrectly.",
+    "The returned UPID can be passed to get_nodes_node_tasks_upid_status to poll task completion."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_status_resume",
+    "post_nodes_node_lxc_vmid_status_stop",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_template.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_template",
+  "usageNotes": "Converts an existing LXC container into a template, allowing it to be cloned for rapid deployment of new containers. The container must be stopped before conversion — running containers cannot be templated. The operation is synchronous (returns null, not a UPID) and is irreversible; once converted, the container is no longer a deployable instance.",
+  "examples": [
+    {
+      "summary": "Convert LXC 200 on node pve1 into a reusable template",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Stop the container before calling this endpoint — Proxmox will reject the request if the container is running.",
+    "Conversion is one-way: there is no API call to revert a template back to a regular container.",
+    "After conversion, clone this template using POST /nodes/{node}/lxc/{vmid}/clone to spin up new instances.",
+    "Templates are visible in the Proxmox UI with a distinct icon and cannot be started directly."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_clone",
+    "post_nodes_node_lxc_vmid_status_stop",
+    "get_nodes_node_lxc_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_termproxy.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_termproxy",
+  "usageNotes": "Creates a TCP terminal proxy session for an LXC container, returning a port, ticket, and UPID needed to open an interactive shell via the Proxmox terminal WebSocket endpoint. The calling user must hold VM.Console on the container's resource path. The container must be running on the target node — calling this against a stopped container or a node that doesn't host the container will fail.",
+  "examples": [
+    {
+      "summary": "Open a terminal proxy session for LXC container 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned ticket is short-lived; connect the WebSocket immediately after receiving it.",
+    "Use the returned port together with the ticket to authenticate the subsequent terminal WebSocket upgrade at /api2/json/nodes/{node}/lxc/{vmid}/vncwebsocket.",
+    "API tokens are supported (allowtoken: true), so automation scripts can obtain a terminal proxy ticket without an interactive login."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_vncproxy",
+    "get_nodes_node_lxc_vmid_status_current",
+    "post_nodes_node_lxc_vmid_status_start"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_lxc_vmid_vncproxy.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_vncproxy",
+  "usageNotes": "Use this to open an interactive console session to a running LXC container via VNC; the response returns a short-lived ticket, one-time password, port, and TLS cert needed to connect a VNC client or Proxmox's noVNC web console. The caller must hold the VM.Console privilege on /vms/{vmid} and the container's node must be online. Enable the 'websocket' flag when connecting through Proxmox's built-in web UI (noVNC); omit it for raw TCP VNC clients.",
+  "examples": [
+    {
+      "summary": "Open a websocket VNC proxy session for LXC 200 on node pve1 at 1280×720",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200
+      },
+      "params": {
+        "websocket": true,
+        "width": 1280,
+        "height": 720
+      }
+    }
+  ],
+  "tips": [
+    "The returned ticket and password are single-use and expire quickly; connect immediately after receiving the response.",
+    "The 'port' in the response is ephemeral and allocated on the target node — ensure your client can reach that node's port directly, not just the API host.",
+    "Width and height only hint the initial console geometry; the container's getty or init system controls the actual terminal size independently.",
+    "If the container is stopped, this call will fail — check container status with get_nodes_node_lxc_vmid_status_current before calling."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_status_current",
+    "post_nodes_node_lxc_vmid_status_start",
+    "post_nodes_node_lxc_vmid_termproxy"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_migrateall.json

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_migrateall",
+  "usageNotes": "Use this to bulk-evacuate all (or a filtered subset of) VMs and containers off a node — typically before maintenance, hardware replacement, or decommissioning. Either 'max-workers' must be specified or 'max_workers' must be set in datacenter.cfg; the call will fail if neither is configured. The endpoint returns a UPID string for an async task; poll the task status via the node tasks API to confirm completion before powering off or removing the source node.",
+  "examples": [
+    {
+      "summary": "Evacuate all guests from pve-node1 to pve-node2 with up to 3 parallel migrations, including guests with local disks",
+      "path_params": {
+        "node": "pve-node1"
+      },
+      "params": {
+        "target": "pve-node2",
+        "max-workers": 3,
+        "with-local-disks": true
+      }
+    }
+  ],
+  "tips": [
+    "Omit 'vms' to migrate everything on the node; pass a comma-separated VMID list to migrate only specific guests.",
+    "Use 'max-workers' (not the deprecated 'maxworkers') for new automation — one of the two must be set or the API returns an error.",
+    "'with-local-disks' triggers live storage migration; without it, guests using only local storage will be skipped or fail to migrate.",
+    "Running guests are live-migrated if the storage is compatible; stopped guests are cold-migrated regardless.",
+    "The returned UPID can be checked with GET /nodes/{node}/tasks/{upid}/status to monitor progress."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_migrate",
+    "post_nodes_node_lxc_vmid_migrate",
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_network.json

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_nodes_node_network",
+  "usageNotes": "Use this to define a new network interface (bridge, bond, VLAN, OVS type, etc.) in the node's /etc/network/interfaces — the config is written to disk but does NOT take effect until you apply pending changes via PUT /nodes/{node}/network. The caller must hold Sys.Modify on /nodes/{node}. Only one of cidr/address+netmask is needed for IPv4; gateway should only be set on the interface that carries the default route.",
+  "examples": [
+    {
+      "summary": "Create a VLAN-aware Linux bridge vmbr1 with a static IP on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "iface": "vmbr1",
+        "type": "bridge",
+        "cidr": "10.10.20.1/24",
+        "autostart": true,
+        "bridge_ports": "eno2",
+        "bridge_vlan_aware": true,
+        "comments": "VM guest traffic bridge - VLAN trunk"
+      }
+    }
+  ],
+  "tips": [
+    "Changes are staged only — always follow up with PUT /nodes/{node}/network (apply) or the node network will remain unchanged until the next reboot or manual ifup.",
+    "For a plain bond, set type=bond and list member interfaces in 'slaves'; for OVS bonds use ovs_bonds instead.",
+    "Setting gateway on more than one interface will produce a broken routing table — only set it on the primary uplink interface.",
+    "bridge_vids is only evaluated when bridge_vlan_aware is true; omit it to allow all VLANs.",
+    "Interface names must be 2–20 characters and follow Linux iface naming rules (no spaces, no slashes)."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network",
+    "get_nodes_node_network_iface",
+    "put_nodes_node_network_iface",
+    "delete_nodes_node_network_iface",
+    "put_nodes_node_network"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_qemu.json

@@ -0,0 +1,46 @@
+{
+  "operationId": "post_nodes_node_qemu",
+  "usageNotes": "Use this to provision a new QEMU/KVM virtual machine on a specific cluster node, or to restore one from a backup archive. The caller must hold VM.Allocate on /vms/{vmid} (or the target pool), Datastore.AllocateSpace on any storage used for disks, and SDN.Use on any bridge or VLAN referenced. The operation returns a task UPID string; poll the task API to determine when provisioning completes before attempting to start or configure the VM.",
+  "examples": [
+    {
+      "summary": "Create a Ubuntu 22.04 cloud-init VM with 2 vCPUs, 2 GiB RAM, a 20 GiB virtio-scsi boot disk, and a bridged NIC",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "vmid": 201,
+        "name": "ubuntu-2204-ci",
+        "ostype": "l26",
+        "cores": 2,
+        "memory": "2048",
+        "bios": "ovmf",
+        "efidisk0": "local-lvm:4,efitype=4m,pre-enrolled-keys=0",
+        "scsi0": "local-lvm:20,discard=on,ssd=1",
+        "scsihw": "virtio-scsi-single",
+        "net0": "virtio,bridge=vmbr0,firewall=1",
+        "agent": "enabled=1",
+        "ciuser": "ubuntu",
+        "ipconfig0": "ip=dhcp",
+        "onboot": 1,
+        "tags": "ubuntu;cloud-init"
+      }
+    }
+  ],
+  "tips": [
+    "vmid must be unique cluster-wide and >= 100; use get_cluster_nextid to obtain a safe next ID before calling this.",
+    "When using 'archive' to restore a backup, VM.Backup permission is sufficient if the VMID already exists; VM.Allocate is required when creating a new VMID.",
+    "Use 'live-restore: true' with 'archive' to start the VM immediately while the restore streams in the background.",
+    "For UEFI/Secure Boot guests set bios=ovmf and include an efidisk0 with efitype=4m; omitting efidisk0 with ovmf will cause the VM to fail to start.",
+    "Cloud-init requires at least one ide/scsi/virtio drive marked as a cloud-init drive (via the Proxmox UI or a separate cloudinit drive param) and the 'agent' param enabled for best results.",
+    "Disk size shorthand uses GiB (e.g. 'local-lvm:20' allocates 20 GiB); the size sub-key inside the disk string is informational only and does not resize the volume."
+  ],
+  "relatedOperations": [
+    "get_cluster_nextid",
+    "get_nodes_node_qemu",
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_status_start",
+    "post_nodes_node_qemu_vmid_clone",
+    "delete_nodes_node_qemu_vmid",
+    "get_nodes_node_tasks"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_qemu_vmid_agent.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent",
+  "usageNotes": "Use this endpoint to execute QEMU Guest Agent (QGA) commands against a running VM that has the guest agent installed and active. The VM must be powered on and the guest agent daemon must be running inside the guest OS; calls will fail with an error if the agent is unreachable. Commands are synchronous and return a `result` object immediately — no UPID is issued. The `fsfreeze-freeze` / `fsfreeze-thaw` pair is commonly used before and after live snapshots to ensure filesystem consistency.",
+  "examples": [
+    {
+      "summary": "Query guest OS network interfaces on VM 101",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {
+        "command": "network-get-interfaces"
+      }
+    }
+  ],
+  "tips": [
+    "Before taking a live snapshot, call `fsfreeze-freeze` then immediately call `fsfreeze-thaw` after the snapshot completes to avoid leaving the guest filesystem in a frozen state.",
+    "`ping` is the cheapest way to verify the guest agent is responsive before issuing more impactful commands.",
+    "`shutdown` via QGA is a clean OS-level shutdown (equivalent to pressing the power button inside the OS), unlike the forceful ACPI or stop calls available through other endpoints.",
+    "`suspend-disk` (hibernate), `suspend-ram` (suspend-to-RAM), and `suspend-hybrid` depend on guest OS support — they will error on guests that lack the capability.",
+    "The caller needs the `VM.GuestAgent.Unrestricted` privilege on `/vms/{vmid}` — a standard API token scoped to a single VM is sufficient."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent",
+    "get_nodes_node_qemu_vmid_agent_fsfreeze_status",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_qemu_vmid_agent_exec.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_exec",
+  "usageNotes": "Use this to run a command inside a running VM via the QEMU guest agent; the VM must be powered on and have the guest agent service running (qemu-guest-agent installed and active). The call returns immediately with the spawned process PID — the command runs asynchronously inside the guest, so use get_nodes_node_qemu_vmid_agent_exec_status with the returned PID to poll for exit code and output. Requires the VM.GuestAgent.Unrestricted privilege on /vms/{vmid}; pass the command as an array (program + args) to avoid shell quoting issues.",
+  "examples": [
+    {
+      "summary": "Run a one-shot hostname check inside VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "command": ["hostname", "-f"]
+      }
+    }
+  ],
+  "tips": [
+    "Pass command as an array, not a shell string — the guest agent does not invoke a shell, so redirection and pipes will not work unless you explicitly invoke the shell (e.g. [\"/bin/sh\", \"-c\", \"echo hello > /tmp/out\"]).",
+    "Use the 'input-data' field to send data to the process's stdin (up to 64 KiB); useful for scripting or piping payloads without writing temp files inside the guest.",
+    "The returned PID belongs to the guest OS namespace, not the hypervisor — it cannot be tracked from the Proxmox host side.",
+    "If the guest agent is not running, the API returns an error immediately; check agent status with get_nodes_node_qemu_vmid_agent_info first."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_exec_status",
+    "get_nodes_node_qemu_vmid_agent_info",
+    "post_nodes_node_qemu_vmid_agent_file_write",
+    "get_nodes_node_qemu_vmid_agent_file_read"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_qemu_vmid_agent_file_write.json

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_file_write",
+  "usageNotes": "Use this to write a file into a running VM via the QEMU Guest Agent (qemu-guest-agent must be installed and running inside the VM). The caller needs the `VM.GuestAgent.FileWrite` or `VM.GuestAgent.Unrestricted` privilege on `/vms/{vmid}`. Content is capped at 60 KB per call; for larger files, write a loader script first and pull the payload from inside the guest.",
+  "examples": [
+    {
+      "summary": "Write a custom resolv.conf into a Linux VM",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105
+      },
+      "params": {
+        "file": "/etc/resolv.conf",
+        "content": "nameserver 1.1.1.1\nnameserver 8.8.8.8\n",
+        "encode": true
+      }
+    }
+  ],
+  "tips": [
+    "The VM must be powered on and the guest agent service must be running — the call will fail with a timeout or error if the agent is not responsive.",
+    "`encode` defaults to true, which lets you pass plain text safely; only set it to false if you are pre-encoding content as base64 yourself.",
+    "The operation returns null on success; no UPID is issued — errors surface as HTTP 5xx/4xx immediately.",
+    "File ownership and permissions inside the guest are determined by the guest agent process user (typically root); adjust permissions with a follow-up exec call if needed.",
+    "The 60 KB (61440 byte) content limit applies to the raw string before base64 expansion; plan multi-part writes for larger payloads."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_file_read",
+    "post_nodes_node_qemu_vmid_agent_exec",
+    "get_nodes_node_qemu_vmid_agent_exec_status",
+    "post_nodes_node_qemu_vmid_agent"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_qemu_vmid_agent_fsfreeze_freeze.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_fsfreeze_freeze",
+  "usageNotes": "Instructs the QEMU Guest Agent inside the VM to freeze all filesystems (fsfreeze), quiescing writes so a consistent snapshot or backup can be taken. The VM must be running with the Guest Agent installed, enabled, and responsive — the call will fail otherwise. Always follow with a thaw (fsfreeze-thaw) as soon as the snapshot is complete, since frozen filesystems block all guest writes and will cause application timeouts.",
+  "examples": [
+    {
+      "summary": "Freeze filesystems on VM 101 before taking a snapshot on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Pair with post_nodes_node_qemu_vmid_agent_fsfreeze_thaw immediately after the snapshot is captured — leaving filesystems frozen will hang guest I/O.",
+    "Check guest agent status first via get_nodes_node_qemu_vmid_agent_info to confirm the agent is running before issuing the freeze.",
+    "Requires the VM.GuestAgent.FileSystemMgmt (or Unrestricted) privilege on /vms/{vmid} — standard VM.PowerMgmt alone is not sufficient.",
+    "The returned result object reflects the Guest Agent's response; a non-error result does not guarantee all filesystems were frozen if the guest OS has uncooperative mounts."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_fsfreeze_thaw",
+    "get_nodes_node_qemu_vmid_agent_fsfreeze_status",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "get_nodes_node_qemu_vmid_agent_info"
+  ]
+}

package/dist/catalog-pve/enrichment/post_nodes_node_qemu_vmid_agent_fsfreeze_status.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_fsfreeze_status",
+  "usageNotes": "Queries the current filesystem freeze state of a running VM via the QEMU Guest Agent; use this to confirm whether filesystems are frozen or thawed before or after backup operations. Requires the guest agent to be installed, running, and responsive inside the VM — the call will fail if the agent is not reachable. One of `VM.GuestAgent.Audit`, `VM.GuestAgent.FileSystemMgmt`, or `VM.GuestAgent.Unrestricted` privilege on `/vms/{vmid}` is sufficient.",
+  "examples": [
+    {
+      "summary": "Check filesystem freeze status on VM 200 running on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response wraps the guest agent reply in a `result` property; inspect `result` for the actual freeze state string (e.g. 'thawed' or 'frozen').",
+    "Call this after issuing fsfreeze-freeze or fsfreeze-thaw to verify the operation took effect before proceeding.",
+    "If the guest agent is not running, Proxmox returns a 500-level error — ensure `qemu-guest-agent` is active inside the guest OS.",
+    "This endpoint takes no body parameters; pass an empty JSON object `{}` or omit the body entirely."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_fsfreeze_freeze",
+    "post_nodes_node_qemu_vmid_agent_fsfreeze_thaw",
+    "get_nodes_node_qemu_vmid_agent",
+    "post_nodes_node_qemu_vmid_agent_get_osinfo"
+  ]
+}