@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_fsfreeze_thaw",
+  "usageNotes": "Call this immediately after a backup, snapshot, or any operation that required a filesystem freeze to resume normal guest I/O; leaving filesystems frozen will cause the guest OS to hang on any write. Requires QEMU Guest Agent to be running inside the VM and the caller to hold either VM.GuestAgent.FileSystemMgmt or VM.GuestAgent.Unrestricted on /vms/{vmid}. This call returns synchronously with a result object — there is no UPID/task to poll.",
+  "examples": [
+    {
+      "summary": "Thaw filesystems on VM 201 after a backup snapshot on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Always pair with post_nodes_node_qemu_vmid_agent_fsfreeze_freeze — never leave a VM frozen; a hung guest will accumulate I/O errors and may require a hard reset.",
+    "The result object returned by the guest agent typically contains the number of filesystems that were thawed; check this value to confirm all filesystems were unfrozen.",
+    "If the guest agent is not running or the freeze/thaw plugin is missing (common on minimal Linux installs), this call will return an error rather than silently succeeding.",
+    "On Windows guests, VSS is used under the hood; ensure the QEMU Guest Agent VSS provider is installed for reliable freeze/thaw behavior."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_fsfreeze_freeze",
+    "post_nodes_node_qemu_vmid_agent_fsfreeze_status",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "get_nodes_node_qemu_vmid_agent"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_fstrim",
+  "usageNotes": "Sends an fstrim command to a running VM via the QEMU Guest Agent, which discards unused blocks on the guest's filesystems — useful after deleting large amounts of data to reclaim thin-provisioned storage on the host. The QEMU Guest Agent must be installed and running inside the VM, and the VM must be powered on. The call returns synchronously with an object wrapping the guest agent's result; there is no UPID/task to poll.",
+  "examples": [
+    {
+      "summary": "Run fstrim on a running Linux VM (VMID 201) hosted on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Guest agent must be installed (qemu-guest-agent package) and the agent service must be running before this call will succeed.",
+    "Effective only on thin-provisioned storage backends (e.g., LVM-thin, ZFS zvols, Ceph RBD); has no meaningful effect on thick-provisioned or raw disk images.",
+    "On Windows guests, ensure the VirtIO driver and guest agent are both installed; fstrim maps to the TRIM/UNMAP path.",
+    "Caller needs VM.GuestAgent.FileSystemMgmt or VM.GuestAgent.Unrestricted on /vms/{vmid} — neither of these is included in the default 'PVEVMUser' role."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent",
+    "post_nodes_node_qemu_vmid_agent_fsfreeze",
+    "post_nodes_node_qemu_vmid_agent_fsthaw",
+    "get_nodes_node_qemu_vmid_agent_fsinfo"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_ping",
+  "usageNotes": "Use this to verify that the QEMU Guest Agent (qemu-guest-agent) is running and responsive inside a VM without disrupting the guest or its workloads. The VM must be powered on and the guest agent service must be installed and started — the call will fail with an error if the agent is not available. Returns immediately with an object containing a `result` property; there is no async UPID.",
+  "examples": [
+    {
+      "summary": "Ping the guest agent on VM 101 running on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A successful response (non-error) confirms the guest agent channel is open; use it as a health-check before issuing agent write commands.",
+    "If the call returns an error such as 'No QEMU guest agent configured', the agent package is missing or the service is stopped inside the guest.",
+    "Requires VM.GuestAgent.Audit OR VM.GuestAgent.Unrestricted on /vms/{vmid} — read-only audit privilege is sufficient."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent",
+    "post_nodes_node_qemu_vmid_agent_get_osinfo",
+    "post_nodes_node_qemu_vmid_agent_get_vcpus"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_set_user_password",
+  "usageNotes": "Use this to reset or set an OS-level user password inside a running QEMU VM without needing SSH access or console login. Requires the QEMU Guest Agent to be installed, running, and responsive inside the guest — the call will fail with a timeout error if the agent is not active. The caller must hold the VM.GuestAgent.Unrestricted privilege on /vms/{vmid}; this is intentionally a high-trust permission because it allows password takeover of any guest OS account.",
+  "examples": [
+    {
+      "summary": "Reset the 'administrator' password on a Windows VM (VMID 201) running on node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {
+        "username": "administrator",
+        "password": "N3wS3cur3Pass!",
+        "crypted": false
+      }
+    }
+  ],
+  "tips": [
+    "The QEMU Guest Agent must be installed inside the guest (qemu-guest-agent package on Linux, VirtIO drivers on Windows) and the agent service must be running before this call will succeed.",
+    "Passwords are transmitted to the Proxmox API over HTTPS and then passed to the guest agent over the virtio-serial channel — they do not traverse the network inside the guest.",
+    "Set 'crypted: true' only when passing a pre-hashed password string (e.g., output of crypt(3)); most callers should leave it false and pass the plaintext password.",
+    "This endpoint does not return a UPID — it is synchronous and returns immediately once the guest agent confirms the change.",
+    "On Linux guests, this uses the guest agent's guest-set-user-password command, which internally calls the passwd utility or equivalent; password complexity rules enforced by the guest OS still apply and may cause the call to fail silently or return an error."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_exec",
+    "get_nodes_node_qemu_vmid_agent_info",
+    "get_nodes_node_qemu_vmid_agent"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_shutdown",
+  "usageNotes": "Sends a graceful shutdown command to the VM via the QEMU Guest Agent (QGA), which triggers a clean OS-level shutdown rather than a hard power-off — the guest OS will flush disk buffers and stop services before halting. The QEMU Guest Agent must be installed and running inside the VM, and the agent service must be enabled on the VM configuration; if the agent is unreachable the call will return an error immediately. Caller needs either VM.PowerMgmt or VM.GuestAgent.Unrestricted on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Gracefully shut down VM 105 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Initiates a full OS shutdown of the running VM, terminating all guest workloads and making the VM unavailable until it is started again.",
+  "tips": [
+    "Unlike POST /nodes/{node}/qemu/{vmid}/status/shutdown, this endpoint routes the shutdown through the guest agent rather than ACPI, giving the OS a chance to handle it via its own shutdown scripts.",
+    "If the guest agent is not responding, fall back to the ACPI-based shutdown at /nodes/{node}/qemu/{vmid}/status/shutdown or a hard stop at /nodes/{node}/qemu/{vmid}/status/stop.",
+    "The response wraps a `result` object from the agent — a null or empty result is normal and indicates the command was accepted; it does not confirm the VM has finished shutting down.",
+    "Monitor VM power state after issuing this call using GET /nodes/{node}/qemu/{vmid}/status/current; wait for status to reach 'stopped' before treating the shutdown as complete."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_status_shutdown",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "post_nodes_node_qemu_vmid_status_reboot",
+    "post_nodes_node_qemu_vmid_agent_ping",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_suspend_disk",
+  "usageNotes": "Instructs the QEMU guest agent inside the VM to suspend the guest to disk (hibernate), writing RAM state to disk and powering off the VM. Requires the QEMU Guest Agent to be installed, running, and connected inside the guest OS; the operation will fail if the agent is not responsive. The caller needs either VM.PowerMgmt or VM.GuestAgent.Unrestricted on the VM path.",
+  "examples": [
+    {
+      "summary": "Hibernate VM 105 on node pve1 to disk via guest agent",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The guest OS must support and be configured for hibernate (suspend-to-disk); Linux guests need a swap partition/file of sufficient size, Windows guests need hibernation enabled.",
+    "After a successful suspend-disk, the VM will appear powered off in Proxmox; resume by starting the VM normally — PVE will restore from the saved disk image.",
+    "If the guest agent is not running or the guest does not support hibernate, the call may return an error or time out without affecting the VM.",
+    "Avoid calling this on VMs with active write I/O (databases, file servers) without quiescing first, as in-flight writes may not complete before the image is saved."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_suspend_ram",
+    "post_nodes_node_qemu_vmid_agent_suspend_hybrid",
+    "post_nodes_node_qemu_vmid_status_start",
+    "get_nodes_node_qemu_vmid_agent_ping"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_suspend_hybrid",
+  "usageNotes": "Instructs the QEMU Guest Agent to perform a hybrid suspend (suspend-to-both: writes memory state to disk as in suspend-to-disk, then suspends to RAM), combining fast resume with crash resilience. Requires the QEMU Guest Agent to be installed, running, and responsive inside the VM — the call will fail if the agent is not reachable. The caller needs either VM.PowerMgmt or VM.GuestAgent.Unrestricted on /vms/{vmid}; the response wraps the agent's raw result in a result property and is synchronous (no UPID is returned).",
+  "examples": [
+    {
+      "summary": "Hybrid-suspend VM 201 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The VM must have the QEMU Guest Agent installed and enabled in the VM hardware config (qemu-guest-agent package + agent: 1 in VM options); otherwise this call returns an error.",
+    "Hybrid suspend requires the guest OS to support it (Windows supports it natively via hybrid shutdown; Linux requires configured swap for the memory image).",
+    "This is a guest-side operation — it tells the OS to suspend itself. For hypervisor-level suspension without guest cooperation, use the node's ACPI or power management endpoints instead.",
+    "Unlike suspend-ram, power is not lost on a hybrid suspend, but the memory image on disk means the guest can recover even if power is cut after the call returns."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_suspend_ram",
+    "post_nodes_node_qemu_vmid_agent_suspend_disk",
+    "post_nodes_node_qemu_vmid_agent_ping",
+    "post_nodes_node_qemu_vmid_agent_get_osinfo",
+    "post_nodes_node_qemu_vmid_status_resume"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_agent_suspend_ram",
+  "usageNotes": "Sends a RAM-only suspend (ACPI S3 sleep) command to a running VM via the QEMU Guest Agent; the VM's memory contents are preserved in RAM while the CPU and most devices are powered down. Requires the QEMU Guest Agent to be installed and running inside the guest, and the caller needs either VM.PowerMgmt or VM.GuestAgent.Unrestricted on /vms/{vmid}. Unlike suspend-disk, this does not checkpoint to storage, so state is lost if the host loses power while the VM is suspended.",
+  "examples": [
+    {
+      "summary": "RAM-suspend VM 105 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The guest OS must support ACPI S3 suspend; Windows guests generally do, but some Linux guests require acpid and appropriate kernel support.",
+    "Confirm the QEMU Guest Agent service is active inside the VM before calling this endpoint — the call will fail silently or return an error if the agent is not responding.",
+    "Use get_nodes_node_qemu_vmid_status_current to verify the VM transitions to 'paused' or 'suspended' state after issuing this command.",
+    "Because state lives only in RAM, avoid this on hosts with unstable power or during planned maintenance windows; use suspend-disk for persistence across host reboots."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_suspend_disk",
+    "post_nodes_node_qemu_vmid_agent_suspend_hybrid",
+    "post_nodes_node_qemu_vmid_status_resume",
+    "get_nodes_node_qemu_vmid_agent",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_clone",
+  "usageNotes": "Use this to create a new VM by cloning an existing VM or template; it returns a task UPID string that you must poll (via get_nodes_node_tasks_upid_status) to confirm completion before using the clone. For normal VMs a full disk copy is always performed, while templates default to a linked clone unless `full: true` is set — linked clones require the source to remain intact and on the same storage. Cross-node cloning (`target`) is only permitted when the source VM's disks reside on shared storage visible to both nodes.",
+  "examples": [
+    {
+      "summary": "Full clone of a template (VM 9000) to a new VM (101) on local-lvm, placed on the same node",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 9000
+      },
+      "params": {
+        "newid": 101,
+        "name": "ubuntu-worker-01",
+        "full": true,
+        "storage": "local-lvm",
+        "description": "Cloned from ubuntu-22.04 template on 2026-06-29"
+      }
+    }
+  ],
+  "tips": [
+    "The returned string is a UPID (e.g. UPID:pve01:...). Poll get_nodes_node_tasks_upid_status until status is 'stopped' and exitstatus is 'OK' before starting or reconfiguring the clone.",
+    "Linked clones (default for templates) share base disk blocks with the source — deleting or moving the source template will break linked clones. Use full: true if the source template may change.",
+    "Cross-node cloning requires shared storage (e.g. Ceph, NFS); disks on node-local storage cannot be cloned to a different target node.",
+    "If you specify `snapname`, the clone is created from that snapshot's disk state rather than the current disk state.",
+    "The caller needs VM.Clone on the source, VM.Allocate on the new VMID (or pool), Datastore.AllocateSpace on the target storage, and SDN.Use on any attached bridge/vnet — missing any of these returns a 403."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_qemu_vmid_config",
+    "put_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_status_start",
+    "delete_nodes_node_qemu_vmid"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_config",
+  "usageNotes": "Use this to modify any VM configuration setting — CPU, memory, disk, network, cloud-init, boot order, tags, and more — without recreating the VM. This is the asynchronous variant: it returns a task UPID string (or null if the task completes within `background_delay` seconds), so callers should poll the task status endpoint when a UPID is returned. Many settings (e.g. memory, CPU count) take effect on the next VM start unless hotplug is enabled for that feature; disk and network changes on a running VM require hotplug to be enabled.",
+  "examples": [
+    {
+      "summary": "Scale up memory and CPU cores on a running VM with hotplug enabled",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105
+      },
+      "params": {
+        "memory": "4096",
+        "cores": 4,
+        "hotplug": "network,disk,cpu,memory,usb",
+        "description": "Web server — scaled up 2026-06-29",
+        "background_delay": 5
+      }
+    }
+  ],
+  "tips": [
+    "Use the `delete` param (comma-separated config key names) to unset options rather than sending an empty value — e.g. `delete: 'description,tags'`.",
+    "Use the `digest` param (SHA1 from a prior GET) to guard against concurrent modification of the same VM config.",
+    "Removing a disk via `delete` moves it to an `unused[n]` entry by default; pass `force: true` only if you want immediate physical deletion.",
+    "Cloud-init settings (ciuser, cipassword, ipconfig[n], etc.) require regenerating the cloud-init drive inside the VM for changes to be applied on next boot.",
+    "The `revert` param lets you roll back a pending (unsaved) change to a specific key without affecting the rest of the config.",
+    "Caller needs at least ONE of the VM.Config.* privileges on /vms/{vmid} — the required privilege depends on which config key is being changed (e.g. VM.Config.Memory for `memory`, VM.Config.Disk for disk params)."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_config",
+    "put_nodes_node_qemu_vmid_config",
+    "get_nodes_node_tasks_upid_status",
+    "post_nodes_node_qemu_vmid_resize",
+    "post_nodes_node_qemu_vmid_move_disk"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_dbus_vmstate",
+  "usageNotes": "Controls the dbus-vmstate helper process for a running QEMU VM, which is required to enable live migration of VMs that use systemd-based guest services relying on D-Bus state. Requires the VM to already be running on the target node; the caller must hold VM.Migrate on the VM path. Returns null synchronously — there is no UPID to poll.",
+  "examples": [
+    {
+      "summary": "Start the dbus-vmstate helper for VM 200 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200
+      },
+      "params": {
+        "action": "start"
+      }
+    }
+  ],
+  "tips": [
+    "The dbus-vmstate helper bridges QEMU's QMP socket with the host D-Bus, allowing live migration to carry over guest service state — start it before initiating a live migration if the guest depends on D-Bus.",
+    "stop the helper after migration completes on the destination, or if the VM is being shut down, to avoid stale socket handles.",
+    "Requires the proxmox-ve package version that ships dbus-vmstate; older clusters may not have the binary installed."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_migrate",
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_status_start"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_firewall_aliases",
+  "usageNotes": "Creates a named IP/CIDR alias scoped to a specific VM's firewall ruleset, making it reusable by name in that VM's firewall rules instead of repeating raw CIDRs. Requires VM.Config.Network on /vms/{vmid}. Alias names must start with a letter and contain only letters, digits, hyphens, or underscores (2–64 chars); names are VM-local and do not propagate to the cluster or datacenter alias pools.",
+  "examples": [
+    {
+      "summary": "Create an alias for a trusted management subnet on VM 201",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 201
+      },
+      "params": {
+        "name": "mgmt-subnet",
+        "cidr": "10.10.0.0/24",
+        "comment": "Internal management VLAN"
+      }
+    }
+  ],
+  "tips": [
+    "Alias names are VM-scoped — the same name can exist independently at the datacenter level or on another VM without conflict.",
+    "Returns null on success; verify creation with the corresponding GET list endpoint.",
+    "Use datacenter-level aliases (POST /cluster/firewall/aliases) for CIDRs shared across multiple VMs or nodes to avoid duplication."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_aliases",
+    "get_nodes_node_qemu_vmid_firewall_aliases_name",
+    "put_nodes_node_qemu_vmid_firewall_aliases_name",
+    "delete_nodes_node_qemu_vmid_firewall_aliases_name",
+    "post_nodes_node_qemu_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_firewall_ipset",
+  "usageNotes": "Creates a named IPSet on a specific VM's firewall, which can then be populated with CIDRs/IPs and referenced in firewall rules. Requires VM.Config.Network on the VM; the VM's firewall must be enabled for IPSets to take effect. The 'rename' parameter doubles as an update path — pass the same value for both 'name' and 'rename' to update only the comment on an existing IPSet.",
+  "examples": [
+    {
+      "summary": "Create an IPSet named 'trusted-mgmt' for a management VM",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {
+        "name": "trusted-mgmt",
+        "comment": "Trusted management IPs for SSH and RDP access"
+      }
+    }
+  ],
+  "tips": [
+    "IPSet names must start with a letter and may only contain letters, digits, hyphens, and underscores (min 2, max 64 chars).",
+    "Creating an IPSet here only registers the set; populate it afterward using the IPSet entries endpoint before referencing it in any firewall rules.",
+    "Use the 'digest' parameter to guard against concurrent edits when scripting changes to a busy VM's firewall config.",
+    "This endpoint is VM-scoped; for cluster-wide shared IPSets use the cluster firewall IPSet endpoints instead."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_ipset",
+    "post_nodes_node_qemu_vmid_firewall_ipset_name",
+    "get_nodes_node_qemu_vmid_firewall_ipset_name",
+    "delete_nodes_node_qemu_vmid_firewall_ipset_name",
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "post_nodes_node_qemu_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_firewall_ipset_name",
+  "usageNotes": "Use this to add an IP address, CIDR block, or IP alias to an existing IPSet on a VM's firewall; the IPSet must already exist before entries can be added. The `nomatch` flag inverts the entry's match logic, useful for carving out exceptions within a broader CIDR. Requires `VM.Config.Network` permission on the target VM.",
+  "examples": [
+    {
+      "summary": "Add a trusted management CIDR to an IPSet named 'mgmt-allow' on VM 105",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105,
+        "name": "mgmt-allow"
+      },
+      "params": {
+        "cidr": "10.10.1.0/24",
+        "comment": "Internal management subnet",
+        "nomatch": false
+      }
+    }
+  ],
+  "tips": [
+    "The IPSet `name` must match pattern [A-Za-z][A-Za-z0-9\\-\\_]+ — it must start with a letter and be 2–64 characters.",
+    "The `cidr` field accepts a plain IP (e.g. 192.168.1.5), a CIDR (e.g. 10.0.0.0/8), or a named alias defined in the firewall alias list.",
+    "Set `nomatch: true` to add a negation entry — useful to exclude a sub-range from a broader CIDR already in the set.",
+    "This call returns null on success; use get_nodes_node_qemu_vmid_firewall_ipset_name to verify the entry was added.",
+    "VM-level IPSets are local to that VM; cluster-level IPSets live under /cluster/firewall/ipset and must be managed separately."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_firewall_ipset",
+    "get_nodes_node_qemu_vmid_firewall_ipset",
+    "get_nodes_node_qemu_vmid_firewall_ipset_name",
+    "put_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+    "delete_nodes_node_qemu_vmid_firewall_ipset_name_cidr"
+  ]
+}

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

@@ -0,0 +1,37 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_firewall_rules",
+  "usageNotes": "Appends a new firewall rule to the VM-level ruleset; the VM's firewall must be enabled (via the VM firewall options) and the cluster/node firewall must also be active for rules to take effect. Requires VM.Config.Network on /vms/{vmid}. The rule is appended to the end of the list unless 'pos' is specified; use 'pos' carefully — rules are evaluated in order and an incorrect position can silently shadow or be shadowed by existing rules.",
+  "examples": [
+    {
+      "summary": "Block all inbound traffic on port 3389 (RDP) from the internet to a Windows VM",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 201
+      },
+      "params": {
+        "type": "in",
+        "action": "DROP",
+        "proto": "tcp",
+        "dport": "3389",
+        "comment": "Block inbound RDP from all sources",
+        "enable": 1,
+        "log": "warning"
+      }
+    }
+  ],
+  "tips": [
+    "Use 'macro' (e.g., 'SSH', 'HTTP', 'HTTPS') instead of manually specifying proto+dport when a standard macro exists — it reduces errors and improves readability.",
+    "Pass 'digest' from a prior GET of the ruleset to guard against concurrent modifications overwriting each other.",
+    "Rules apply per-VM and are independent of node-level or cluster-level firewall rules; all three layers stack.",
+    "The 'iface' param for VMs must match a VM network key like 'net0', 'net1', etc. — not a host interface name.",
+    "A rule with 'enable': 0 is saved but inactive; useful for staging rules before activating them."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "get_nodes_node_qemu_vmid_firewall_rules_pos",
+    "put_nodes_node_qemu_vmid_firewall_rules_pos",
+    "delete_nodes_node_qemu_vmid_firewall_rules_pos",
+    "get_nodes_node_qemu_vmid_firewall_options",
+    "put_nodes_node_qemu_vmid_firewall_options"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_migrate",
+  "usageNotes": "Use this to move a QEMU VM from one cluster node to another; set `online: true` for live migration of a running VM (brief network blip only), or omit it to migrate an offline VM with zero downtime risk. The call returns a UPID task ID immediately — poll `get_nodes_node_tasks_upid_status` to confirm completion before treating the VM as stable on the target. If the VM has local disks and no shared storage, you must also pass `with-local-disks: true` and a valid `targetstorage` mapping, or use `force: true` (root only) to override the guard.",
+  "examples": [
+    {
+      "summary": "Live-migrate a running VM to another node, moving its local disk to the target's local-lvm storage",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {
+        "target": "pve2",
+        "online": true,
+        "with-local-disks": true,
+        "targetstorage": "local-lvm",
+        "migration_type": "secure",
+        "bwlimit": 102400
+      }
+    }
+  ],
+  "destructiveReason": "Migrating with `online: false` (or when the VM is already stopped) shuts the VM down on the source node and deletes its local disk images there once copied to the target; a failed mid-migration transfer can leave disk data in an inconsistent state.",
+  "tips": [
+    "Both the source and target nodes must be members of the same Proxmox cluster; cross-cluster migration is not supported via this endpoint.",
+    "For VMs on shared storage (Ceph, NFS, iSCSI) you can omit `targetstorage` entirely — the disk stays in place and only the config is moved.",
+    "Use `migration_type: insecure` only on a fully isolated, private migration VLAN to get better throughput; the default `secure` tunnels traffic over SSH.",
+    "`with-conntrack-state` is useful for stateful firewalls (e.g., Proxmox VE firewall with NAT) — migrate connection tracking entries so existing TCP sessions survive the move.",
+    "A non-zero `bwlimit` (in KiB/s) prevents the migration from saturating your management network during business hours; 102400 = 100 MB/s."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_qemu_vmid_migrate",
+    "post_nodes_node_qemu_vmid_status_stop"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_monitor",
+  "usageNotes": "Sends a raw QEMU monitor command to a running VM; the VM must be in a running state on the specified node or the command will fail. Read-only introspection commands (info, ?, help) require only Sys.Audit, while most state-changing commands require Sys.Modify, and a subset of device/migration/dump commands are root-only. The response is a plain string containing the monitor output, not a task UPID — execution is synchronous.",
+  "examples": [
+    {
+      "summary": "Query memory balloon target on VM 105",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105
+      },
+      "params": {
+        "command": "info balloon"
+      }
+    }
+  ],
+  "tips": [
+    "Send 'info status' to quickly check whether a VM is running, paused, or shutdown without fetching the full VM config.",
+    "Use 'system_powerdown' (requires Sys.Modify) to trigger a graceful ACPI shutdown; prefer this over a hard stop when the guest OS responds to ACPI events.",
+    "Root-only commands (device_add, migrate, screendump, etc.) will be rejected for API token users even with full privileges — they require a root@pam session.",
+    "Commands marked deprecated in the permissions description (stopcapture, wavcapture) may be removed in future QEMU versions; avoid relying on them.",
+    "The monitor interface is stateless per request; multi-step QEMU monitor workflows (e.g. savevm then loadvm) must be issued as separate API calls."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_status_start",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "post_nodes_node_qemu_vmid_status_reset",
+    "post_nodes_node_qemu_vmid_status_suspend"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_move_disk",
+  "usageNotes": "Use this to relocate a VM disk to a different storage pool (e.g., migrating from local-lvm to a Ceph or NFS datastore) or to reassign a disk to a different VM on the same node. Returns a task UPID — poll the tasks API to track completion, as the copy operation runs asynchronously and duration scales with disk size. Without 'delete: true', the source disk is retained as an unused slot on the original VM, which will consume storage until manually removed.",
+  "examples": [
+    {
+      "summary": "Move VM 101 boot disk from local-lvm to a Ceph pool, deleting the original after copy",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {
+        "disk": "scsi0",
+        "storage": "ceph-pool",
+        "format": "raw",
+        "delete": true
+      }
+    }
+  ],
+  "tips": [
+    "The VM does not need to be stopped for this operation — live disk moves are supported, but the VM must remain on the same node; cross-node moves require a full migration instead.",
+    "Omitting 'format' preserves the source disk format; specify 'raw' when moving to Ceph/RBD since those pools do not support qcow2.",
+    "When moving a disk to another VM ('target-vmid'), supply 'target-disk' if you need it mapped to a specific controller slot; otherwise it inherits the source key, which may conflict if that slot is occupied on the target VM.",
+    "Use 'digest' and 'target-digest' to guard against concurrent config changes — read the VM config first to obtain the current digest value.",
+    "Use 'bwlimit' to cap I/O during production hours and avoid saturating storage network bandwidth."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_config",
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status",
+    "post_nodes_node_qemu_vmid_resize"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_mtunnel",
+  "usageNotes": "This endpoint is intended exclusively for internal use by Proxmox's VM live-migration subsystem — do not call it directly from user-facing automation or scripts. It establishes the migration tunnel on the destination node, returning a socket path, an authentication ticket, and a task UPID that tracks the tunnel process. Requires both VM.Allocate on the target VM and Sys.Incoming on the cluster root; additional permission checks occur when the actual migration data transfer begins.",
+  "examples": [
+    {
+      "summary": "Open a migration tunnel for VM 105 on destination node pve2, pre-checking storage 'local-lvm' and bridge 'vmbr0'",
+      "path_params": {
+        "node": "pve2",
+        "vmid": 105
+      },
+      "params": {
+        "storages": "local-lvm",
+        "bridges": "vmbr0"
+      }
+    }
+  ],
+  "tips": [
+    "The returned 'socket' and 'ticket' are consumed by the source node's migration driver — they are not meant for manual use.",
+    "Pre-flight bridge and storage checks performed here are repeated during the actual data transfer; a pass here does not guarantee a pass at transfer time.",
+    "The UPID in the response can be polled via GET /nodes/{node}/tasks/{upid}/status to monitor tunnel lifecycle."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_migrate",
+    "get_nodes_node_tasks_upid_status",
+    "post_nodes_node_qemu_vmid_mtunnelwebsocket"
+  ]
+}

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

@@ -0,0 +1,35 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_remote_migrate",
+  "usageNotes": "Use this endpoint to migrate a QEMU VM from the local cluster to a completely separate, unrelated Proxmox cluster (remote migration). This is an EXPERIMENTAL feature — prefer the standard intra-cluster migrate endpoint when both source and target nodes share the same cluster. The caller must supply a `target-endpoint` with a valid API token for the remote cluster and explicit bridge/storage mappings; the operation returns a UPID task string that must be polled via the tasks API to track completion. By default the source VM is left stopped on the source cluster after migration; pass `delete: true` to remove it automatically only after a confirmed successful transfer.",
+  "examples": [
+    {
+      "summary": "Live-migrate VM 102 from node pve1 to a remote cluster, deleting the source after success",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 102
+      },
+      "params": {
+        "target-endpoint": "apitoken=PVEAPIToken=root@pam!migrate=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=remote-pve.example.com,fingerprint=AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99",
+        "target-bridge": "vmbr0",
+        "target-storage": "local-lvm",
+        "online": true,
+        "delete": true,
+        "bwlimit": 102400
+      }
+    }
+  ],
+  "tips": [
+    "The `target-endpoint` API token must have sufficient privileges on the remote cluster (at minimum VM.Allocate and Datastore.AllocateSpace on the destination).",
+    "Use `target-bridge: '1'` or `target-storage: '1'` as shorthand to map each source bridge/storage to an identically-named resource on the target — useful when both clusters share the same naming scheme.",
+    "Online migration across clusters requires the VM's disks to be on shared or replicable storage; non-shared local storage will cause the task to fail if `online: true`.",
+    "The returned UPID can be polled with GET /nodes/{node}/tasks/{upid}/status; check for `exitstatus: OK` before concluding the migration succeeded.",
+    "If `target-vmid` is omitted, the remote cluster will attempt to use the same VMID — ensure there is no ID collision on the target beforehand.",
+    "Set `bwlimit` (in KiB/s) to throttle disk transfer and avoid saturating the WAN link during business hours."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_migrate",
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}