@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_certificates_custom",
+  "usageNotes": "Use this to install a third-party or internally signed TLS certificate on a specific Proxmox node's web GUI (pveproxy). The caller must hold Sys.Modify on /nodes/{node}. Set restart: true to apply the certificate immediately — without it, pveproxy continues serving the old cert until manually restarted. If an ACME-managed certificate is already present, pass force: true to overwrite it; otherwise the request will fail.",
+  "examples": [
+    {
+      "summary": "Upload a Let's Encrypt cert bundle with private key and immediately restart pveproxy",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "certificates": "-----BEGIN CERTIFICATE-----\nMIIE...base64...==\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIE...intermediate...==\n-----END CERTIFICATE-----",
+        "key": "-----BEGIN PRIVATE KEY-----\nMIIE...base64key...==\n-----END PRIVATE KEY-----",
+        "force": true,
+        "restart": true
+      }
+    }
+  ],
+  "tips": [
+    "The certificates field must be a full PEM chain — leaf cert first, followed by any intermediates — to avoid browser trust errors.",
+    "If you omit the key param, Proxmox expects the private key was previously uploaded or is embedded in the existing keystore; for a clean install always supply the key.",
+    "The response returns the parsed cert metadata (fingerprint, notafter, SANs) synchronously — there is no UPID; verify the fingerprint in the response before confirming success.",
+    "restart: true triggers a graceful pveproxy reload; active API/web sessions will reconnect automatically within a few seconds.",
+    "To revert to a self-signed cert, use the DELETE endpoint for custom certificates rather than uploading a blank value."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_certificates_info",
+    "delete_nodes_node_certificates_custom",
+    "get_nodes_node_certificates_acme_certificate",
+    "post_nodes_node_certificates_acme_certificate"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_disks_directory",
+  "usageNotes": "Use this to format an unused block device with ext4 or xfs and mount it as a directory-backed storage under '/mnt/pve/NAME'. The target device must be completely unpartitioned and unused — Proxmox will refuse if the disk has any existing partition table or filesystem. The operation returns a task UPID; poll the task status to confirm completion before referencing the new storage.",
+  "examples": [
+    {
+      "summary": "Format /dev/sdb with ext4 and register it as a Proxmox directory storage named 'local-data'",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "device": "/dev/sdb",
+        "name": "local-data",
+        "filesystem": "ext4",
+        "add_storage": true
+      }
+    }
+  ],
+  "tips": [
+    "Use get_nodes_node_disks_list first to identify unused disks (those with no partition table reported).",
+    "Setting add_storage=true saves a separate step but requires the calling token/user to also hold 'Datastore.Allocate' on /storage, in addition to Sys.Modify on /.",
+    "xfs is preferred for large sequential workloads (e.g. backup targets, ISO stores); ext4 is the safe default for general use.",
+    "Once created, the directory storage appears in Datacenter > Storage and is immediately usable for VM disks, backups, and ISOs depending on content types configured afterward.",
+    "To undo, you must manually remove the storage from Proxmox config and unmount/wipe the device — there is no API delete counterpart for this specific create path."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_list",
+    "get_nodes_node_disks_directory",
+    "delete_nodes_node_disks_directory_name",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_disks_initgpt",
+  "usageNotes": "Use this to wipe and initialize a raw block device on a PVE node with a fresh GPT partition table before creating partitions or adding the disk to a storage pool. The disk must not be mounted or in use (e.g. not part of an active ZFS pool or LVM group). Returns a UPID string; poll the tasks API to confirm completion before issuing follow-up disk operations.",
+  "examples": [
+    {
+      "summary": "Initialize /dev/sdb with a new GPT table on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "disk": "/dev/sdb"
+      }
+    }
+  ],
+  "tips": [
+    "Check current disk usage first via get_nodes_node_disks_list to confirm the target disk is not mounted or part of an existing storage.",
+    "Omit the uuid parameter to let Proxmox generate a random GPT UUID automatically — only supply it when you need a deterministic UUID (e.g. scripted reprovisioning).",
+    "After the task UPID completes, the disk will have a GPT label but no partitions — use subsequent partition/storage APIs to finish setup.",
+    "Requires Sys.Modify at the root path; API tokens must have this privilege explicitly granted."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_list",
+    "post_nodes_node_disks_directory",
+    "post_nodes_node_disks_lvm",
+    "post_nodes_node_disks_lvmthin",
+    "post_nodes_node_disks_zfs",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_disks_lvm",
+  "usageNotes": "Use this to initialize a raw block device as an LVM Volume Group (VG) on a specific node — a prerequisite before any LVM-backed or LVM-thin storage can be added. The target device must be unpartitioned and not in use; Proxmox will wipe it and create a new PV+VG. Returns a task UPID string (async); poll the task to confirm completion before using the new VG. Set add_storage=true to simultaneously register the VG as a Proxmox storage entry, which additionally requires Datastore.Allocate on /storage.",
+  "examples": [
+    {
+      "summary": "Create a VG named 'data-vg' on /dev/sdb and auto-register it as a storage pool",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "device": "/dev/sdb",
+        "name": "data-vg",
+        "add_storage": true
+      }
+    }
+  ],
+  "tips": [
+    "The device path must be an absolute block device path (e.g. /dev/sdb, /dev/nvme0n1) — partitions like /dev/sdb1 may be rejected.",
+    "If the disk has existing partition tables or LVM metadata, Proxmox will refuse to create the VG; wipe it first via the disk wipe endpoint (POST /nodes/{node}/disks/wipe).",
+    "The 'name' field follows pve-storage-id format: alphanumeric plus hyphens, no spaces.",
+    "If you omit add_storage, you must manually add the storage via the storage API (POST /storage) after the task completes."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_lvm",
+    "delete_nodes_node_disks_lvm_name",
+    "post_nodes_node_disks_lvmthin",
+    "post_nodes_node_disks_wipe",
+    "get_nodes_node_disks_list"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_disks_lvmthin",
+  "usageNotes": "Use this to initialize a raw block device as an LVM thin-pool on a specific node — a prerequisite for VM/CT disk storage backed by thin provisioning. The target device must be unpartitioned and unused (no existing filesystem or LVM metadata); the operation is irreversible on that device's data. Returns a task UPID; poll the task endpoint to confirm completion before referencing the pool as storage.",
+  "examples": [
+    {
+      "summary": "Create a thinpool named 'vmdata' on /dev/sdb and auto-register it as a PVE storage",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "device": "/dev/sdb",
+        "name": "vmdata",
+        "add_storage": true
+      }
+    }
+  ],
+  "tips": [
+    "Verify the device is truly unused first via get_nodes_node_disks_list (or lsblk on the node) — LVM initialization will destroy any existing data.",
+    "Setting add_storage=true requires the calling token/user to also hold Datastore.Allocate on /storage, in addition to Sys.Modify on /.",
+    "The thinpool name must conform to pve-storage-id format (alphanumeric, hyphens, underscores; no spaces); it becomes the storage ID visible across the cluster.",
+    "After creation, the thinpool appears as a 'lvmthin' storage type in datacenter storage; set content types (images, rootdir) separately via the storage edit endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_list",
+    "get_nodes_node_disks_lvmthin",
+    "delete_nodes_node_disks_lvmthin_name",
+    "get_storage",
+    "post_storage"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_nodes_node_disks_zfs",
+  "usageNotes": "Use this endpoint to create a new ZFS pool on a specific node using one or more raw block devices; the node must be online and the caller must hold the Sys.Modify privilege on /. The operation returns a task UPID — poll the task status endpoint to confirm completion before treating the pool as available. Setting add_storage=true automatically registers the zpool as a Proxmox storage entry and additionally requires the Datastore.Allocate privilege on /storage.",
+  "examples": [
+    {
+      "summary": "Create a 3-disk RAIDZ1 pool named 'tank' on pve1 with LZ4 compression and auto-register it as storage",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "name": "tank",
+        "devices": "sdb,sdc,sdd",
+        "raidlevel": "raidz",
+        "compression": "lz4",
+        "ashift": 12,
+        "add_storage": true
+      }
+    }
+  ],
+  "tips": [
+    "ashift should match the physical sector size of your drives: 12 for 4K-native drives (most modern HDDs/SSDs), 9 for 512-byte legacy drives. Mismatched ashift degrades performance permanently and cannot be changed after pool creation.",
+    "draid and draid2/draid3 levels require the draid-config parameter (data and spares values); omitting it will cause the request to fail.",
+    "Devices must not be in use by another zpool, partition table, or filesystem — use get_nodes_node_disks_list to identify eligible 'available' disks first.",
+    "lz4 is the recommended default compression for most workloads; zstd offers higher ratios for cold data at higher CPU cost.",
+    "mirror requires an even number of devices (minimum 2); raid10 requires at least 4 devices."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_zfs",
+    "get_nodes_node_disks_list",
+    "delete_nodes_node_disks_zfs_name",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_execute",
+  "usageNotes": "Use this endpoint to run multiple PVE API commands against a single node in one round-trip, guaranteed in order. Access is restricted to the root@pam user — API tokens scoped to other users will be rejected regardless of privileges. The response is a synchronous array of per-command results (not a UPID), so all commands must complete before the response returns; avoid long-running commands in a batch.",
+  "examples": [
+    {
+      "summary": "Query node version and cluster status in a single batch call",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "commands": "[{\"method\":\"GET\",\"path\":\"/version\",\"args\":{}},{\"method\":\"GET\",\"path\":\"/cluster/status\",\"args\":{}}]"
+      }
+    }
+  ],
+  "tips": [
+    "The commands value must be a JSON-encoded string (i.e., a string whose content is a JSON array), not a raw JSON array — double-encode it when constructing requests programmatically.",
+    "Commands execute sequentially; a failure in one command does not abort subsequent commands — check each result object individually for errors.",
+    "Only root@pam can call this endpoint; API token auth is allowed only when the token belongs to root@pam.",
+    "Prefer individual API calls for single operations; this batch endpoint is most useful for reducing latency when several read queries are needed together."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status",
+    "get_version",
+    "get_cluster_status"
+  ]
+}

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

@@ -0,0 +1,37 @@
+{
+  "operationId": "post_nodes_node_firewall_rules",
+  "usageNotes": "Appends a new rule to the host-level firewall ruleset on the specified node; requires Sys.Modify on /nodes/{node}. The node firewall must be enabled separately — adding rules here has no effect if the host firewall is disabled in the node's firewall options. Use the 'pos' parameter to insert at a specific position; omit it to append at the end.",
+  "examples": [
+    {
+      "summary": "Block inbound SSH from a specific external IP on the host firewall",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "type": "in",
+        "action": "DROP",
+        "proto": "tcp",
+        "source": "203.0.113.45",
+        "dport": "22",
+        "comment": "Block SSH brute-force from known bad IP",
+        "enable": 1,
+        "log": "warning"
+      }
+    }
+  ],
+  "tips": [
+    "Rules on this endpoint apply to the Proxmox host itself, not to VM/CT guest traffic — use the VM or CT firewall endpoints for guest-level rules.",
+    "The 'digest' field can be fetched from GET /nodes/{node}/firewall/rules and passed here to guard against concurrent edits.",
+    "Use 'macro' (e.g., 'SSH', 'HTTP', 'HTTPS') instead of manually specifying proto+dport for common services — macros expand to the correct protocol and port automatically.",
+    "Setting 'enable': 0 creates the rule in a disabled state, useful for staging rules before activating them.",
+    "Rules are evaluated top-down; use 'pos' to control insertion order relative to existing rules."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_firewall_rules",
+    "get_nodes_node_firewall_rules_pos",
+    "put_nodes_node_firewall_rules_pos",
+    "delete_nodes_node_firewall_rules_pos",
+    "get_nodes_node_firewall_options",
+    "put_nodes_node_firewall_options"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_nodes_node_hosts",
+  "usageNotes": "Use this to overwrite `/etc/hosts` on a specific Proxmox node — for example, to add or update static hostname-to-IP mappings needed before DNS is available, or to propagate cluster-wide hostname entries to a node that hasn't rejoined DNS yet. The caller must hold `Sys.Modify` on `/nodes/{node}`. Always retrieve the current file first (via `get_nodes_node_hosts`) and pass its digest to prevent concurrent-write conflicts.",
+  "examples": [
+    {
+      "summary": "Add a static host entry for a new VM to pve1's /etc/hosts",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "data": "127.0.0.1 localhost\n::1 localhost ip6-localhost ip6-loopback\n\n192.168.10.10 pve1.lab.local pve1\n192.168.10.11 pve2.lab.local pve2\n192.168.10.100 vm-web01.lab.local vm-web01\n",
+        "digest": "a3f1e2b4c5d6e7f8a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4"
+      }
+    }
+  ],
+  "tips": [
+    "Fetch the current content and digest with get_nodes_node_hosts before writing — the digest field is your optimistic-lock guard against concurrent edits.",
+    "Returns null on success; any HTTP error (403, 500) means the write did not occur.",
+    "Changes take effect immediately — no service restart required — but only affect the targeted node; repeat the call for each node in the cluster.",
+    "The `data` field must contain the complete file content, not just new lines; partial updates are not supported."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_hosts"
+  ]
+}

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

@@ -0,0 +1,42 @@
+{
+  "operationId": "post_nodes_node_lxc",
+  "usageNotes": "Use this to provision a new LXC container or restore one from a backup/template on a specific cluster node. The caller must supply a valid `vmid` (>= 100, unique across the cluster) and an `ostemplate` pointing to a storage-resident template or vzdump archive; the node must be online and the target storage must have `Datastore.AllocateSpace` permission granted. The response is a task UPID — the container is created asynchronously, so poll the task status before assuming the container is ready.",
+  "examples": [
+    {
+      "summary": "Create an Ubuntu 22.04 unprivileged container with 2 cores, 1 GB RAM, 8 GB rootfs, and a DHCP network interface",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "vmid": 120,
+        "ostemplate": "local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst",
+        "hostname": "web-proxy",
+        "cores": 2,
+        "memory": 1024,
+        "swap": 512,
+        "rootfs": "local-lvm:8",
+        "net0": "name=eth0,bridge=vmbr0,ip=dhcp,firewall=1",
+        "unprivileged": 1,
+        "start": 1,
+        "timezone": "host",
+        "tags": "ubuntu;prod",
+        "ssh-public-keys": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... admin@nightsquawk.tech"
+      }
+    }
+  ],
+  "tips": [
+    "The return value is a UPID string (e.g. 'UPID:pve1:...'). Use get_nodes_node_tasks_upid_status to poll completion before interacting with the new container.",
+    "Omitting `rootfs` does not auto-allocate disk; always specify it explicitly using the STORAGE_ID:SIZE_IN_GiB shorthand (e.g. 'local-lvm:8') to avoid creation failures.",
+    "For privileged containers (unprivileged=0), the API caller also needs 'Sys.Modify' on '/' — this is a common permission error when using restricted API tokens.",
+    "When restoring from a vzdump backup, set `restore: true` alongside the backup path in `ostemplate`; this preserves the original container config stored inside the archive.",
+    "DNS settings (nameserver, searchdomain) default to the host's values if omitted — explicitly set them if the container needs different resolvers.",
+    "Use `unique: true` when cloning or restoring to avoid MAC address collisions across containers."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc",
+    "get_nodes_node_lxc_vmid_status",
+    "post_nodes_node_lxc_vmid_status_start",
+    "delete_nodes_node_lxc_vmid",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_clone",
+  "usageNotes": "Use this to clone an existing LXC container into a new container with a distinct VMID; the operation is asynchronous and returns a UPID task string that must be polled via the task API to confirm completion. For normal (non-template) containers a full disk copy is always performed, so ensure the target storage has sufficient free space before cloning. Cross-node cloning (via 'target') is only permitted when the source container resides on shared storage accessible to both nodes.",
+  "examples": [
+    {
+      "summary": "Full clone of container 110 to new container 200 on the same node, placed in pool 'clients'",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {
+        "newid": 200,
+        "hostname": "ct-clone-200",
+        "description": "Clone of ct-110 for staging",
+        "full": true,
+        "storage": "local-zfs",
+        "pool": "clients"
+      }
+    }
+  ],
+  "tips": [
+    "The return value is a UPID (e.g. 'UPID:pve01:...'). Poll GET /nodes/{node}/tasks/{upid}/status to wait for the clone to finish before starting the new container.",
+    "Linked clones (full=false) are only possible when the source is a CT template; attempting them on a running or stopped regular container silently falls back to a full clone.",
+    "If you specify 'snapname', the clone is created from that snapshot's disk state rather than the current disk — useful for golden-image workflows.",
+    "Cross-node cloning requires the caller to also hold 'Datastore.AllocateSpace' on the target storage and 'SDN.Use' on any bridge the new container will use.",
+    "The 'bwlimit' parameter throttles disk I/O during the copy in KiB/s; leave it unset on lightly loaded nodes to let the storage layer use its configured default."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "post_nodes_node_lxc_vmid_snapshot",
+    "post_nodes_node_lxc",
+    "delete_nodes_node_lxc_vmid"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_firewall_aliases",
+  "usageNotes": "Use this to create a named IP or CIDR alias in a specific LXC container's firewall scope, allowing firewall rules for that container to reference human-readable names instead of raw addresses. The caller must hold VM.Config.Network on /vms/{vmid}. Returns null on success — no UPID is issued; the alias is applied synchronously.",
+  "examples": [
+    {
+      "summary": "Create an alias named 'mgmt-net' pointing to the management subnet for LXC 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {
+        "name": "mgmt-net",
+        "cidr": "10.10.0.0/24",
+        "comment": "Internal management network"
+      }
+    }
+  ],
+  "tips": [
+    "Alias names must start with a letter and contain only letters, digits, hyphens, or underscores (min 2, max 64 chars).",
+    "Aliases defined here are container-scoped — they are not visible to other VMs or to the datacenter/cluster firewall alias pool.",
+    "After creation, reference the alias by name in container firewall rules using the 'source' or 'dest' fields.",
+    "To update an alias, use the PUT sibling endpoint; this POST will error if the name already exists."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_aliases",
+    "get_nodes_node_lxc_vmid_firewall_aliases_name",
+    "put_nodes_node_lxc_vmid_firewall_aliases_name",
+    "delete_nodes_node_lxc_vmid_firewall_aliases_name",
+    "post_nodes_node_lxc_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_firewall_ipset",
+  "usageNotes": "Creates a named IPSet on an LXC container's firewall, which can then be populated with IP/CIDR entries and referenced in firewall rules. The caller needs VM.Config.Network on the container. The 'rename' param doubles as an in-place update: pass it with the same value as 'name' to update only the comment on an existing IPSet without recreating it.",
+  "examples": [
+    {
+      "summary": "Create an IPSet named 'trusted-mgmt' for management traffic on LXC 110",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {
+        "name": "trusted-mgmt",
+        "comment": "Management subnet whitelist"
+      }
+    }
+  ],
+  "tips": [
+    "IPSet names must start with a letter and match [A-Za-z][A-Za-z0-9\\-\\_]+ (2–64 chars) — purely numeric names are rejected.",
+    "Creating the IPSet is a two-step process: create it here, then add individual IP/CIDR entries via the corresponding PUT endpoint for IPSet members.",
+    "Use the 'digest' param when scripting concurrent changes to avoid race conditions overwriting the firewall config.",
+    "Returns null on success — check for a 2xx HTTP status rather than parsing a body."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_ipset",
+    "post_nodes_node_lxc_vmid_firewall_ipset_name",
+    "get_nodes_node_lxc_vmid_firewall_ipset_name",
+    "delete_nodes_node_lxc_vmid_firewall_ipset_name",
+    "get_nodes_node_lxc_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_firewall_ipset_name",
+  "usageNotes": "Adds a single IP address, CIDR block, or alias to a named IPSet on an LXC container's firewall; the IPSet must already exist before calling this endpoint. Requires VM.Config.Network permission on the target container. The `nomatch` flag inverts the entry's match logic, useful for carving out exclusions within a broader allow/deny rule referencing the IPSet.",
+  "examples": [
+    {
+      "summary": "Add a trusted office CIDR to an existing 'trusted-hosts' IPSet on LXC 120",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 120,
+        "name": "trusted-hosts"
+      },
+      "params": {
+        "cidr": "203.0.113.0/24",
+        "comment": "Office public IP range",
+        "nomatch": false
+      }
+    }
+  ],
+  "tips": [
+    "The IPSet must be created first via the corresponding POST /ipset endpoint before entries can be added.",
+    "The 'cidr' field accepts a bare IP (e.g. '10.0.0.5'), a CIDR block (e.g. '10.0.0.0/24'), or an alias name prefixed with '+' if defined in the firewall alias list.",
+    "Setting 'nomatch' to true turns this entry into a negation — the IPSet rule will explicitly exclude this CIDR rather than match it.",
+    "Changes take effect immediately in the firewall rule evaluation; no container restart is needed.",
+    "IPSets are container-local; entries added here are not shared with the node-level or cluster-level firewall IPSets."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_firewall_ipset",
+    "get_nodes_node_lxc_vmid_firewall_ipset_name",
+    "get_nodes_node_lxc_vmid_firewall_ipset_name_cidr",
+    "put_nodes_node_lxc_vmid_firewall_ipset_name_cidr",
+    "delete_nodes_node_lxc_vmid_firewall_ipset_name_cidr"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_firewall_rules",
+  "usageNotes": "Appends a new firewall rule to the per-container rule chain for the specified LXC guest; the container-level firewall must be enabled (via the container's firewall options) and the node firewall must also be active for rules to take effect. The caller requires VM.Config.Network on /vms/{vmid}. Rules are inserted at the end by default; supply 'pos' to place the rule at a specific zero-based position in the chain.",
+  "examples": [
+    {
+      "summary": "Block all inbound traffic on port 23 (Telnet) from any source on container 110",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {
+        "type": "in",
+        "action": "DROP",
+        "proto": "tcp",
+        "dport": "23",
+        "comment": "Block Telnet inbound",
+        "enable": 1,
+        "log": "warning"
+      }
+    }
+  ],
+  "tips": [
+    "Use 'macro' (e.g. 'SSH', 'HTTP', 'HTTPS') instead of manually specifying proto/dport when targeting well-known services — macros keep rules readable and reduce mistakes.",
+    "The 'digest' param can be passed (read from a prior GET of the rules list) to prevent a lost-update race if multiple operators may edit the ruleset concurrently.",
+    "For LXC interfaces, 'iface' must match the container's network key name (e.g. 'net0', 'net1') — arbitrary interface names accepted for host rules are NOT valid here.",
+    "New rules are inactive until 'enable' is explicitly set to 1; omitting 'enable' creates the rule in a disabled state.",
+    "Do not mix IPv4 and IPv6 addresses in a single 'source' or 'dest' value — use separate rules for each address family."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_rules",
+    "put_nodes_node_lxc_vmid_firewall_rules_pos",
+    "delete_nodes_node_lxc_vmid_firewall_rules_pos",
+    "get_nodes_node_lxc_vmid_firewall_options",
+    "put_nodes_node_lxc_vmid_firewall_options"
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_migrate",
+  "usageNotes": "Initiates an LXC container migration to another cluster node; returns a task UPID immediately — poll the task log to track completion. For running containers, set `online: true` for live migration (minimal downtime) or `restart: true` to shut down, migrate, then restart; omitting both requires the container to already be stopped. The caller needs `VM.Migrate` on `/vms/{vmid}` and the target node must be reachable within the cluster.",
+  "examples": [
+    {
+      "summary": "Live-migrate a running container to a second node, mapping its storage to the target pool",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {
+        "target": "pve2",
+        "online": true,
+        "target-storage": "local-lvm",
+        "bwlimit": 102400
+      }
+    }
+  ],
+  "destructiveReason": "Migrating a running container with `online` causes a brief service interruption during final sync; using `restart` shuts the container down on the source node, and a failed migration may leave it offline until manually started.",
+  "tips": [
+    "The returned string is a UPID (e.g. UPID:pve1:...:vzdump:...); use GET /nodes/{node}/tasks/{upid}/status to poll for completion.",
+    "If `target-storage` is omitted and the source storage is not shared across nodes, migration will fail — always specify a mapping for local storage.",
+    "Setting `bwlimit: 0` disables throttling entirely; useful on a quiet link but can saturate a production network.",
+    "Restart migration respects the `timeout` parameter (default 180 s) for the shutdown phase — increase it for containers with slow stop scripts.",
+    "Use GET /nodes/{node}/lxc/{vmid}/migrate to check pre-migration feasibility before issuing the POST."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_migrate",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log",
+    "post_nodes_node_lxc_vmid_status_shutdown",
+    "post_nodes_node_lxc_vmid_status_start"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_move_volume",
+  "usageNotes": "Use this to migrate an LXC rootfs or mount-point volume to a different storage pool (e.g., local-lvm to ceph), or to reassign a volume from one container to another. The operation returns a task UPID and runs asynchronously — poll the task status before assuming completion. Without `delete: true`, the source volume is retained as an `unusedN` entry in the container config and will consume storage until manually removed.",
+  "examples": [
+    {
+      "summary": "Move rootfs of LXC 201 from local storage to ceph-rbd, deleting the original",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 201
+      },
+      "params": {
+        "volume": "rootfs",
+        "storage": "ceph-rbd",
+        "delete": true
+      }
+    }
+  ],
+  "tips": [
+    "The container does not need to be stopped for a mount-point (mp*) move, but moving rootfs on a running container may fail or require a shutdown depending on storage type.",
+    "When moving a volume to a different container (target-vmid), both the source and target containers must be on the same node; use target-volume to control which config key it lands on.",
+    "Supply `digest` (from the current container config) and `target-digest` when scripting to guard against concurrent config changes.",
+    "Omitting `storage` while supplying `target-vmid` reassigns the volume to the target container on the same storage — useful for splitting a cloned container's disks."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_lxc_vmid_config",
+    "delete_nodes_node_lxc_vmid_unlink"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_mtunnel",
+  "usageNotes": "This endpoint is used exclusively by Proxmox's internal CT live-migration machinery to establish the migration tunnel on the destination node; it should not be called directly by external tooling or scripts. Requires both VM.Allocate on the target VMID and Sys.Incoming at the root level on the destination node. Returns a socket path, a ticket, and a UPID — the UPID can be polled via the tasks API to track tunnel/migration progress.",
+  "examples": [
+    {
+      "summary": "Open a migration tunnel for CT 112 on destination node pve2, pre-checking storage 'local-lvm' and bridge 'vmbr0'",
+      "path_params": {
+        "node": "pve2",
+        "vmid": 112
+      },
+      "params": {
+        "storages": "local-lvm",
+        "bridges": "vmbr0"
+      }
+    }
+  ],
+  "tips": [
+    "The bridges and storages params are pre-flight checks only — Proxmox re-validates the actually-used resources during migration itself.",
+    "The returned socket is a Unix socket path on the destination node used for the migration data stream; it is consumed by the source node automatically.",
+    "Poll the returned UPID against GET /nodes/{node}/tasks/{upid}/status to monitor tunnel and migration state.",
+    "Sys.Incoming is a rarely granted privilege; ensure the destination node's API user has it at '/' before invoking migration flows."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_migrate",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_lxc_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "operationId": "post_nodes_node_lxc_vmid_remote_migrate",
+  "usageNotes": "Use this to migrate an LXC container to a different Proxmox cluster (cross-cluster migration); this is distinct from intra-cluster migration and is marked EXPERIMENTAL — avoid in production without prior testing. The three required body params — target-endpoint, target-bridge, and target-storage — must all be resolvable on the destination cluster before the task is submitted. Returns a UPID task string; poll GET /nodes/{node}/tasks/{upid}/status to track completion. By default the source container is left stopped on the source cluster after migration; pass delete=true only if you are certain the migration succeeded and want automatic cleanup.",
+  "examples": [
+    {
+      "summary": "Live-migrate CT 201 from node pve1 to a remote cluster, mapping bridges and storage, keeping the source after migration",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 201
+      },
+      "params": {
+        "target-endpoint": "apitoken=PVEAPIToken=root@pam!migrate-token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=10.0.1.50,fingerprint=AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67,port=8006",
+        "target-bridge": "vmbr0",
+        "target-storage": "local-lvm",
+        "online": true,
+        "delete": false,
+        "bwlimit": 102400
+      }
+    }
+  ],
+  "tips": [
+    "The target-endpoint API token must have VM.Allocate and Datastore.AllocateSpace on the destination cluster, not just on the source.",
+    "Use target-vmid to assign a different VMID on the destination if the original VMID is already in use there.",
+    "If the container uses multiple storage volumes on different source storages, supply a full mapping string (e.g. 'local-lvm:remote-lvm,local:remote-data') rather than a single storage ID.",
+    "restart migration (restart=true) shuts the CT down gracefully, transfers it, then boots it on the destination — useful when the workload cannot tolerate live-migration overhead.",
+    "The TLS fingerprint in target-endpoint can be obtained from the destination node's certificate via: openssl s_client -connect HOST:8006 2>/dev/null | openssl x509 -fingerprint -sha256 -noout"
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_migrate",
+    "get_nodes_node_tasks",
+    "get_nodes_node_lxc_vmid_status_current"
+  ]
+}