Tool reference

proxmox-mcp has 314 tools in 19 toolsets: 156 read, 107 write, 44 delete and 7 exec. It also has 8 prompts.

Each tool is labelled with the setting it needs:

Label	Registered when
🟢 read	Always
🟠 write	PROXMOX_ALLOW_WRITES=true
🔴 delete	PROXMOX_ALLOW_WRITES=true and PROXMOX_ALLOW_DELETES=true
🟣 exec	PROXMOX_ALLOW_WRITES=true and PROXMOX_ALLOW_EXEC=true

Every tool also needs its toolset to be enabled in PROXMOX_TOOLSETS, which enables all toolsets by default. Tools that act on a VM or container take its vmid and find the node automatically; node-scoped tools default to PROXMOX_DEFAULT_NODE or the only node. Tools that start a Proxmox task wait for it by default (wait), up to PROXMOX_TASK_TIMEOUT_MS.

Contents

• cluster: Cluster overview, nodes and guests at a glance, datacenter options, corosync config, metric servers and bulk guest actions.
• nodes: Node status and statistics, services, network interfaces, DNS, time, updates and repositories, subscriptions, certificates and ACME, logs and node power.
• vms: QEMU virtual machines: status, configuration, power, create, clone, disks, migration, templates, cloud-init and statistics.
• containers: LXC containers: status, configuration, power, create, clone, volumes, migration, templates, interfaces and statistics.
• agent: The QEMU guest agent: OS, network and filesystem information from inside VMs, filesystem freeze/trim, and (with exec enabled) running commands and reading/writing files.
• snapshots: Snapshots of VMs and containers: list, create, roll back, describe and delete, plus a cluster-wide view of stale snapshots.
• storage: Storage definitions and usage, volumes and content, ISO/template downloads, storage discovery, physical disks, SMART, ZFS and LVM.
• backup: vzdump backup jobs, ad-hoc backups, backup listing and verification state, restores, pruning and guests without backups.
• tasks: Proxmox tasks (UPIDs): list, inspect, read logs, wait for and stop them.
• access: Users, groups, roles, ACLs, API tokens, authentication realms, effective permissions and two-factor authentication.
• firewall: Firewall rules, options, aliases, IP sets and security groups at datacenter, node and guest level, plus the firewall log.
• ha: High availability: status, HA resources, groups and rules, and HA-managed migration.
• sdn: Software-defined networking: zones, VNets, subnets, controllers, IPAM and DNS, and applying pending SDN changes.
• ceph: Ceph: health, OSDs, pools, monitors, managers, metadata servers, CephFS, flags and configuration.
• pools: Resource pools and their members.
• replication: Storage replication jobs, their status and logs.
• notifications: Notification targets (sendmail, SMTP, Gotify, webhooks) and matchers.
• hardware: PCI and USB devices, mediated devices, resource mappings, CPU models and QEMU capabilities.
• raw: A raw API escape hatch for anything the other tools don’t cover. It is limited to GET requests unless writes are enabled.

cluster

Cluster overview, nodes and guests at a glance, datacenter options, corosync config, metric servers and bulk guest actions.

Tool	Access	Summary
proxmox_get_version	🟢 read	Get Proxmox VE version
proxmox_get_cluster_status	🟢 read	Get cluster overview
proxmox_list_nodes	🟢 read	List nodes
proxmox_list_guests	🟢 read	List VMs and containers
proxmox_list_resources	🟢 read	List cluster resources
proxmox_get_next_vmid	🟢 read	Get next free VMID
proxmox_get_cluster_log	🟢 read	Get cluster log
proxmox_get_cluster_options	🟢 read	Get datacenter options
proxmox_get_cluster_config	🟢 read	Get cluster (corosync) configuration
proxmox_list_metric_servers	🟢 read	List metric servers
proxmox_simulate_schedule	🟢 read	Simulate a job schedule
proxmox_update_cluster_options	🟠 write	Update datacenter options
proxmox_save_metric_server	🟠 write	Create or update a metric server
proxmox_delete_metric_server	🔴 delete	Delete a metric server
proxmox_bulk_guest_action	🟠 write	Bulk start, shut down, suspend or migrate guests

proxmox_get_version

🟢 read

Get the Proxmox VE version and release of the API endpoint this server talks to.

No arguments.

proxmox_get_cluster_status

🟢 read

One-call overview of the whole cluster: name, quorum, Proxmox version, every node (online state, CPU, memory, uptime), guest counts by state, totals, storage usage and HA state. A good first call.

No arguments.

proxmox_list_nodes

🟢 read

List the cluster’s nodes with online state, CPU and memory usage, uptime and subscription level.

Argument	Type	Required	Description
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_list_guests

🟢 read

List virtual machines and containers across the cluster with status, node, CPU, memory, disk, uptime, tags and pool. Filter by type, node, status, tag, pool or a search string, and sort by resource use.

Argument	Type	Required	Description
type	"vm" | "container"		Only VMs (qemu) or only containers (lxc)
node	string		Only guests on this node
status	"running" | "stopped" | "paused" | "suspended"		Only guests in this state
tag	string		Only guests with this tag
pool	string		Only guests in this resource pool
templates	"include" | "exclude" | "only"		How to treat templates (default include)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
sort	"vmid" | "name" | "cpu" | "memory" | "disk" | "uptime"		Sort order (default vmid); cpu/memory/disk/uptime sort highest first
limit	integer		Maximum number of results (default 500)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_list_resources

🟢 read

List cluster resources of any kind from /cluster/resources: nodes, guests, storage, pools and SDN zones. Use proxmox_list_guests for a friendlier guest list.

Argument	Type	Required	Description
type	"node" | "vm" | "storage" | "pool" | "sdn"		Resource type (default all)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 1000)

proxmox_get_next_vmid

🟢 read

Get the next free VM/container ID, or check whether a specific ID is free.

Argument	Type	Required	Description
vmid	integer		Check whether this ID is free instead

proxmox_get_cluster_log

🟢 read

Read recent entries of the cluster log (task starts/ends, logins and other cluster events from all nodes).

Argument	Type	Required	Description
max	integer		Maximum number of entries (default 50)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_cluster_options

🟢 read

Get datacenter-wide options (datacenter.cfg): keyboard, console, migration network/type, HA shutdown policy, bandwidth limits, MAC prefix, tag style, next-id range and more.

No arguments.

proxmox_get_cluster_config

🟢 read

Get the corosync cluster configuration: member nodes with their IDs, votes and link addresses, the totem settings, and the join information (fingerprint, addresses) used to add nodes.

No arguments.

proxmox_list_metric_servers

🟢 read

List external metric servers (InfluxDB, Graphite, OpenTelemetry) that Proxmox sends performance data to.

No arguments.

proxmox_simulate_schedule

🟢 read

Show the next run times of a Proxmox calendar-event schedule (as used by backup, replication and other jobs), e.g. ‘mon..fri 02:00’ or ‘*/15’. Useful to check a schedule before saving it.

Argument	Type	Required	Description
schedule	string	yes	Calendar event, e.g. ‘daily’, ‘sat 03:30’, ‘*/2:00’
iterations	integer		How many run times to show (default 10)
starttime	integer		Start from this UNIX time instead of now

proxmox_update_cluster_options

🟠 write · destructive

Change datacenter-wide options (datacenter.cfg). Only the given fields change. Common ones are typed; anything else (bwlimit, ha, crs, migration, next-id, tag-style, u2f, webauthn, notify…) can be set via extra in Proxmox’s property-string format.

Argument	Type	Required	Description
keyboard	string		Default VNC keyboard layout, e.g. en-gb
language	string		Default GUI language, e.g. en
console	"applet" | "vv" | "html5" | "xtermjs"		Default console viewer
email_from	string		Sender address for notification emails
http_proxy	string		Proxy for downloads (e.g. http://proxy:3128)
mac_prefix	string		Prefix for auto-generated MAC addresses
max_workers	integer		Maximum parallel workers for bulk actions
migration	string		Migration settings, e.g. ‘type=insecure,network=10.0.0.0/24’
ha	string		HA settings, e.g. ‘shutdown_policy=migrate’
description	string		Datacenter notes (Markdown)
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_save_metric_server

🟠 write

Create (create=true) or update an external metric server for InfluxDB, Graphite or OpenTelemetry. Only the given fields change on update.

Argument	Type	Required	Description
id	string	yes	Metric server ID
create	boolean		Create a new server (default false = update an existing one)
type	"influxdb" | "graphite" | "opentelemetry"		Server type (required when creating)
server	string		Server address (required when creating)
port	integer		Server port (required when creating)
disable	boolean		Disable sending metrics
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_metric_server

🔴 delete · destructive

Remove an external metric server configuration.

Argument	Type	Required	Description
id	string	yes	Metric server ID

proxmox_bulk_guest_action

🟠 write · destructive

Start, shut down, suspend or migrate many VMs and containers at once with Proxmox’s bulk action (Proxmox VE 9+). Select guests with vmids; for migrate also give target. Runs as one task.

Argument	Type	Required	Description
action	"start" | "shutdown" | "suspend" | "migrate"	yes	What to do
vmids	integer[]	yes	Guest IDs to act on
target	string		Target node (migrate only)
online	boolean		Live-migrate running VMs and restart-migrate running containers (migrate only)
timeout	integer		Shutdown timeout in seconds before giving up (shutdown only)
force_stop	boolean		Hard-stop guests that don’t shut down within the timeout (shutdown only)
with_local_disks	boolean		Also migrate local disks of running VMs (migrate only)
to_disk	boolean		Suspend to disk (hibernate) instead of to RAM (suspend only)
max_workers	integer		How many guests to handle in parallel
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

nodes

Node status and statistics, services, network interfaces, DNS, time, updates and repositories, subscriptions, certificates and ACME, logs and node power.

Tool	Access	Summary
proxmox_get_node_status	🟢 read	Get node status
proxmox_get_node_stats	🟢 read	Get node performance history
proxmox_get_node_netstat	🟢 read	Get guest network counters
proxmox_get_node_report	🟢 read	Get node system report
proxmox_query_url_metadata	🟢 read	Query URL metadata
proxmox_list_node_services	🟢 read	List node services
proxmox_manage_node_service	🟠 write	Start, stop, restart or reload a node service
proxmox_list_node_network	🟢 read	List node network interfaces
proxmox_get_node_network_interface	🟢 read	Get a node network interface
proxmox_save_node_network_interface	🟠 write	Create or update a node network interface
proxmox_delete_node_network_interface	🔴 delete	Delete a node network interface
proxmox_apply_node_network	🟠 write	Apply pending network changes
proxmox_revert_node_network	🟠 write	Discard pending network changes
proxmox_get_node_dns	🟢 read	Get node DNS settings
proxmox_set_node_dns	🟠 write	Set node DNS settings
proxmox_get_node_hosts	🟢 read	Get node /etc/hosts
proxmox_set_node_hosts	🟠 write	Write node /etc/hosts
proxmox_get_node_time	🟢 read	Get node time and time zone
proxmox_set_node_timezone	🟠 write	Set node time zone
proxmox_get_node_config	🟢 read	Get node options
proxmox_update_node_config	🟠 write	Update node options
proxmox_node_power	🟠 write	Reboot or shut down a node
proxmox_wake_node	🟠 write	Wake a node with wake-on-LAN
proxmox_node_bulk_action	🟠 write	Start, stop, suspend or migrate all guests on a node
proxmox_get_node_syslog	🟢 read	Read node syslog
proxmox_get_node_journal	🟢 read	Read node systemd journal
proxmox_list_node_updates	🟢 read	List available package updates
proxmox_refresh_node_updates	🟠 write	Refresh package index
proxmox_get_package_changelog	🟢 read	Get package changelog
proxmox_get_node_package_versions	🟢 read	Get Proxmox package versions
proxmox_list_node_repositories	🟢 read	List APT repositories
proxmox_set_node_repository	🟠 write	Enable, disable or add an APT repository
proxmox_get_node_subscription	🟢 read	Get node subscription
proxmox_set_node_subscription	🟠 write	Set or refresh node subscription
proxmox_delete_node_subscription	🔴 delete	Remove node subscription key
proxmox_get_node_certificates	🟢 read	Get node certificates
proxmox_upload_node_certificate	🟠 write	Upload a custom node certificate
proxmox_delete_node_certificate	🔴 delete	Delete the custom node certificate
proxmox_node_acme_certificate	🟠 write	Order, renew or revoke an ACME certificate
proxmox_list_acme_accounts	🟢 read	List ACME accounts
proxmox_get_acme_account	🟢 read	Get ACME account
proxmox_save_acme_account	🟠 write	Register or update an ACME account
proxmox_delete_acme_account	🔴 delete	Deactivate an ACME account
proxmox_list_acme_directories	🟢 read	List ACME directories
proxmox_list_acme_plugins	🟢 read	List ACME challenge plugins
proxmox_get_acme_plugin	🟢 read	Get ACME plugin
proxmox_get_acme_challenge_schema	🟢 read	Get ACME DNS plugin schema
proxmox_save_acme_plugin	🟠 write	Create or update an ACME plugin
proxmox_delete_acme_plugin	🔴 delete	Delete an ACME plugin

proxmox_get_node_status

🟢 read

Detailed status of one node: CPU model/sockets/cores and usage, IO wait, load average, memory/swap/root filesystem usage, kernel, Proxmox VE version, boot mode (EFI/BIOS, secure boot), uptime, KSM sharing and the subscription status. Use proxmox_list_nodes for all nodes at a glance and proxmox_get_node_stats for history.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_node_stats

🟢 read

Node performance history from the RRD database (CPU, IO wait, load, memory, swap, root disk, network, ARC…) over a timeframe, summarized as min/avg/max/last per metric plus a short downsampled series. Network values are bytes per second.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
timeframe	"hour" | "day" | "week" | "month" | "year" | "decade"		Time window (default hour)
cf	"AVERAGE" | "MAX"		RRD consolidation function (default AVERAGE)
metrics	string[]		Only these metrics, e.g. [“cpu”, “memused”, “netin”] (default all)
points	integer		Number of points in the downsampled series (default 12)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_node_netstat

🟢 read

Traffic counters of the guests’ tap/veth network devices on a node (bytes in/out per device and VMID), as seen from the host.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
vmid	integer		Only this guest

proxmox_get_node_report

🟢 read

The node’s pvereport: a long text dump of versions, hardware, storage, network, cluster and guest configuration, as used for support requests. Large; truncated to max_chars. Can take a while to generate.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
max_chars	integer		Truncate the text to this many characters (default 50000)

proxmox_query_url_metadata

🟢 read

Ask a node to look up a URL’s file name, size and MIME type (HEAD request from the node). Useful before proxmox_download_to_storage to check the URL and pick the file name.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
url	string	yes	The URL to inspect, e.g. https://cdimage.debian.org/.../debian-13.iso
verify_certificates	boolean		Verify TLS certificates (default true)

proxmox_list_node_services

🟢 read

List the Proxmox-related system services on a node (pveproxy, pvedaemon, corosync, pve-cluster, chrony, sshd, postfix…) with their running state and whether they are enabled. Failed services are listed first.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_manage_node_service

🟠 write · destructive

Start, stop, restart or reload a system service on a node, e.g. restart pveproxy after a certificate change. Stopping pve-cluster, corosync, pveproxy or pvedaemon can cut off API access or cluster communication; prefer reload where possible.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
service	string	yes	Service ID, e.g. pveproxy, pvedaemon, pvestatd, corosync, pve-cluster, chrony, sshd, postfix (see proxmox_list_node_services)
action	"start" | "stop" | "restart" | "reload"	yes	What to do; reload falls back to restart if the service can’t reload
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_list_node_network

🟢 read

List a node’s network configuration: physical NICs, Linux bridges, bonds, VLANs and OVS objects with addresses, gateways, ports and comments. Interfaces that are configured but not active are flagged; that usually means pending (unapplied) changes from proxmox_save_node_network_interface, or a down link. Apply with proxmox_apply_node_network or discard with proxmox_revert_node_network.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
type	"bridge" | "bond" | "eth" | "alias" | "vlan" | "fabric" | "OVSBridge" | "OVSBond" | "OVSPort" | "OVSIntPort" | "vnet" | "any_bridge" | "any_local_bridge" | "include_sdn"		Only this interface type (any_bridge = Linux and OVS bridges)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_node_network_interface

🟢 read

Get the configuration of one network interface on a node (as stored in /etc/network/interfaces, including pending changes).

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
iface	string	yes	Interface name, e.g. vmbr0, bond0, eno1, vmbr0.20
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_save_node_network_interface

🟠 write

Create (create=true) or update a network interface on a node: Linux bridge, bond, VLAN, NIC address etc. Changes are only written to /etc/network/interfaces.new and stay pending until proxmox_apply_node_network (or are discarded with proxmox_revert_node_network). On update, only the given fields change; remove settings with delete. Lists of ports/slaves are given as arrays.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
iface	string	yes	Interface name, e.g. vmbr1, bond0, vmbr0.20, vlan20
create	boolean		Create a new interface (default false = update an existing one)
type	"bridge" | "bond" | "eth" | "alias" | "vlan" | "fabric" | "OVSBridge" | "OVSBond" | "OVSPort" | "OVSIntPort" | "vnet" | "unknown"		Interface type (required when creating; looked up when updating)
cidr	string		IPv4 address with prefix, e.g. 192.168.1.10/24
gateway	string		IPv4 default gateway
cidr6	string		IPv6 address with prefix
gateway6	string		IPv6 default gateway
bridge_ports	string[]		Bridge ports, e.g. [“eno1”] (bridge); [] for none
bridge_vlan_aware	boolean		Make the bridge VLAN aware (bridge)
bridge_vids	string		Allowed VLANs on a VLAN-aware bridge, e.g. ‘2-4094’ or ‘10 20 100-200’
slaves	string[]		Bond member interfaces, e.g. [“eno1”, “eno2”] (bond)
bond_mode	"balance-rr" | "active-backup" | "balance-xor" | "broadcast" | "802.3ad" | "balance-tlb" | "balance-alb" | "balance-slb" | "lacp-balance-slb" | "lacp-balance-tcp"		Bonding mode (bond)
bond_primary	string		Primary interface for active-backup bonds
bond_xmit_hash_policy	"layer2" | "layer2+3" | "layer3+4"		Transmit hash policy for balance-xor/802.3ad bonds
vlan_raw_device	string		Parent interface of a VLAN, e.g. vmbr0 (vlan)
vlan_id	integer		VLAN tag for a custom-named VLAN interface (vlan)
mtu	integer		MTU
autostart	boolean		Bring the interface up at boot
comments	string		Comment
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_node_network_interface

🔴 delete · destructive

Remove a network interface (bridge, bond, VLAN…) from a node’s configuration. Like other network edits it stays pending until proxmox_apply_node_network. Guests attached to a removed bridge lose connectivity once applied.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
iface	string	yes	Interface name, e.g. vmbr1

proxmox_apply_node_network

🟠 write · destructive

Apply a node’s pending network changes (ifreload). Can interrupt connectivity to the node and its guests, and a wrong bridge/gateway can lock you out of the node; review pending changes with proxmox_list_node_network first.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
regenerate_frr	boolean		Also regenerate the FRR (SDN fabric routing) configuration
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_revert_node_network

🟠 write

Discard all pending (unapplied) network changes on a node, keeping the running configuration.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_get_node_dns

🟢 read

Get a node’s DNS resolver settings: search domain and up to three name servers.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_set_node_dns

🟠 write · destructive

Set a node’s DNS search domain and name servers (/etc/resolv.conf). Fields left out keep their current value; pass an empty string to clear dns2/dns3.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
search	string		Search domain, e.g. example.lan
dns1	string		First name server IP
dns2	string		Second name server IP
dns3	string		Third name server IP

proxmox_get_node_hosts

🟢 read

Read a node’s /etc/hosts file and its digest (pass the digest to proxmox_set_node_hosts to avoid overwriting concurrent edits).

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_set_node_hosts

🟠 write · destructive

Replace a node’s /etc/hosts with the given content. Read it first with proxmox_get_node_hosts and pass its digest. The node’s own name must keep resolving to its cluster IP or pve-cluster can break.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
content	string	yes	The complete new content of /etc/hosts
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_get_node_time

🟢 read

Get a node’s current time (UTC), local time and configured time zone. Useful for spotting clock drift between nodes.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_set_node_timezone

🟠 write

Set a node’s time zone, e.g. Europe/London or UTC.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
timezone	string	yes	Time zone name from zone.tab, e.g. Europe/London, America/New_York, UTC

proxmox_get_node_config

🟢 read

Get a node’s own options (/etc/pve/nodes//config): notes/description, wake-on-LAN MAC, ACME account and domains, start-on-boot delay, ballooning target and location, plus the digest for safe updates.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_update_node_config

🟠 write

Change a node’s options: notes/description, wake-on-LAN MAC, ACME account and certificate domains (used by proxmox_node_acme_certificate), start-on-boot delay, ballooning target. Only the given fields change; remove with delete.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
description	string		Node notes (Markdown), shown in the web UI
wakeonlan	string		Wake-on-LAN MAC address, optionally with options, e.g. ‘aa:bb:cc:dd:ee:ff,bind-interface=vmbr0’
startall_onboot_delay	integer		Seconds to wait before starting on-boot guests
ballooning_target	integer		RAM usage target for ballooning, in percent
acme_account	string		ACME account name for this node’s certificate (see proxmox_list_acme_accounts)
acme_domains	object[]		Certificate domains (acmedomain0..5); replaces the existing list
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_node_power

🟠 write · destructive

Reboot or shut down a Proxmox node. Running guests are shut down or stopped by the node first (HA guests may be migrated per the HA shutdown policy). Consider proxmox_node_bulk_action migrate first to move guests away. A shut-down node can only be brought back by hand, IPMI or proxmox_wake_node.

Argument	Type	Required	Description
node	string	yes	Node name (see proxmox_list_nodes)
command	"reboot" | "shutdown"	yes	reboot or shutdown

proxmox_wake_node

🟠 write

Send a wake-on-LAN packet to a powered-off node (sent by another cluster node). The node needs its wake-on-LAN MAC set in its options (proxmox_update_node_config wakeonlan).

Argument	Type	Required	Description
node	string	yes	Node name (see proxmox_list_nodes)

proxmox_node_bulk_action

🟠 write · destructive

Run a bulk action over the guests on one node: start (by default only guests with onboot=1; force=true for all), stop (shut down, hard-stopping after a timeout), suspend (VMs only) or migrate (all guests to target, e.g. before node maintenance). Restrict with vmids. Runs as one task. For a selection across nodes use proxmox_bulk_guest_action.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
action	"start" | "stop" | "suspend" | "migrate"	yes	What to do with the node’s guests
vmids	integer[]		Only these guests (default all on the node)
target	string		Target node (migrate only, required)
force	boolean		start: also start guests without onboot=1
force_stop	boolean		stop: hard-stop guests that don’t shut down within the timeout (default true)
timeout	integer		stop: per-guest shutdown timeout in seconds (default 180)
with_local_disks	boolean		migrate: live-migrate local disks too
max_workers	integer		Parallel jobs (default from datacenter max_workers; migrate needs one of the two)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_get_node_syslog

🟢 read

Read a node’s system log (journal rendered as syslog lines), optionally for one service and a time range. Page with start/limit. For the raw systemd journal with ‘last N lines’ semantics use proxmox_get_node_journal.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
service	string		Only this service/unit, e.g. pveproxy, pvedaemon, corosync, pve-cluster
since	string		Start time, e.g. ‘2026-01-31 08:00:00’ or ‘yesterday’
until	string		End time, same format as since
start	integer		Line offset to start from (default 0)
limit	integer		Maximum number of results (default 200)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_node_journal

🟢 read

Read a node’s systemd journal: the last N entries (default 100) or a time range, optionally only one unit, a syslog identifier, a priority level or kernel messages.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
lastentries	integer		Only the last N entries (default 100 when no range is given)
since	string | number		Start of the range: epoch seconds or a date like “2026-01-31 12:00:00” / ISO 8601
until	string | number		End of the range: epoch seconds or a date like “2026-01-31 12:00:00” / ISO 8601
unit	string		Only this systemd unit, e.g. pveproxy (.service implied)
identifier	string		Only messages whose syslog identifier matches this glob, e.g. ‘pve*’
priority	string		Only this priority or more severe: 0 (emerg) .. 7 (debug), or a range ‘LOW..HIGH’; e.g. 3 for errors
kernel	boolean		Only kernel messages
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_list_node_updates

🟢 read

List the package updates available on a node (from the last package index refresh) with installed and new versions, origin and priority, plus counts. Run proxmox_refresh_node_updates first for fresh results. Installing updates is not available through the API.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 300)

proxmox_refresh_node_updates

🟠 write

Refresh a node’s package index (apt-get update) so proxmox_list_node_updates shows current updates. Runs as a task.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
notify	boolean		Send a notification about new packages
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_get_package_changelog

🟢 read

Get the changelog of a package available on a node, e.g. to see what an update to pve-manager or proxmox-kernel changes. Truncated to max_chars.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
package	string	yes	Package name, e.g. pve-manager
version	string		Package version (default the candidate version)
max_chars	integer		Truncate the text to this many characters (default 20000)

proxmox_get_node_package_versions

🟢 read

List the installed versions of the important Proxmox packages on a node (like pveversion -v), including the running kernel.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_list_node_repositories

🟢 read

List a node’s APT repositories by file with enabled/disabled state, URIs, suites and components, any parse errors and warnings (e.g. enterprise repo without subscription, mixed suites), and which standard Proxmox repositories are configured. Use path/index and the digest with proxmox_set_node_repository.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_set_node_repository

🟠 write

Enable or disable an existing APT repository (give path and index from proxmox_list_node_repositories plus enabled), or add a standard Proxmox repository by handle (e.g. no-subscription, enterprise, test, ceph-squid-no-subscription). Refresh with proxmox_refresh_node_updates afterwards.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
handle	string		Add this standard repository, e.g. ‘no-subscription’ or ‘enterprise’ (see standard_repos)
path	string		File of the repository to change, e.g. /etc/apt/sources.list.d/pve-enterprise.sources
index	integer		Index of the repository within the file
enabled	boolean		Enable (true) or disable (false) the repository at path/index
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_get_node_subscription

🟢 read

Get a node’s subscription status, level, product, sockets and next due date. The key itself is never shown.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_set_node_subscription

🟠 write

Set a node’s subscription key (key given), or re-check the existing subscription with the Proxmox shop server (no key). Returns the resulting status; the key is never echoed back.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
key	string		Subscription key, e.g. pve2c-0123456789 (omit to just refresh the status)
force	boolean		Refresh: contact the server even if the cached status is still valid

proxmox_delete_node_subscription

🔴 delete · destructive

Remove the subscription key from a node (e.g. before moving it to other hardware). The enterprise repository stops working without it.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_get_node_certificates

🟢 read

List the TLS certificates of a node’s web interface/API (pve-root-ca, pve-ssl and any custom or ACME pveproxy-ssl certificate) with subject, issuer, SANs, validity, days left and fingerprint. Private keys are never returned.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_upload_node_certificate

🟠 write · destructive

Install a custom TLS certificate (PEM chain) and private key for a node’s web interface/API (pveproxy-ssl). Replaces an existing custom/ACME certificate only with force=true; restart=true restarts pveproxy to use it. The key is sent to Proxmox only and never returned.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
certificates	string	yes	PEM certificate chain (server certificate first)
key	string		PEM private key (required unless a key is already installed)
force	boolean		Overwrite an existing custom or ACME certificate
restart	boolean		Restart pveproxy to load the new certificate

proxmox_delete_node_certificate

🔴 delete · destructive

Remove a node’s custom (or ACME) web certificate and key, falling back to the self-signed pve-ssl certificate. restart=true restarts pveproxy.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
restart	boolean		Restart pveproxy afterwards

proxmox_node_acme_certificate

🟠 write · destructive

Order a new ACME (e.g. Let’s Encrypt) certificate for a node, renew it, or revoke it at the CA. The node’s ACME account and domains must be set first (proxmox_update_node_config acme_account/acme_domains; accounts via proxmox_save_acme_account, DNS plugins via proxmox_save_acme_plugin). Runs as a task; pveproxy reloads the new certificate. revoke needs delete access (PROXMOX_ALLOW_DELETES).

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
action	"order" | "renew" | "revoke"	yes	order a new certificate, renew the existing one, or revoke it
force	boolean		order: overwrite an existing custom certificate; renew: renew even if more than 30 days remain
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_list_acme_accounts

🟢 read

List the cluster’s registered ACME accounts (used to order node certificates), with their CA directory and contacts.

No arguments.

proxmox_get_acme_account

🟢 read

Get an ACME account’s details: CA directory, account URL (location), status, contacts and accepted terms of service. Keys are redacted.

Argument	Type	Required	Description
name	string		Account name (default ‘default’)

proxmox_save_acme_account

🟠 write

Register a new ACME account with a CA (create=true; Let’s Encrypt by default, accepting its terms of service with tos_url from proxmox_list_acme_directories), or update an existing account’s contact email (or refresh it when no contact is given). Runs as a task.

Argument	Type	Required	Description
name	string		Account name (default ‘default’)
create	boolean		Register a new account (default false = update)
contact	string		Contact email address(es), comma-separated (required when creating)
directory	string		ACME directory URL (create only; default Let’s Encrypt production)
tos_url	string		Terms of service URL being agreed to (create only; required by most CAs)
eab_kid	string		External account binding key ID (create only, for CAs that require EAB)
eab_hmac_key	string		External account binding HMAC key (create only)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_delete_acme_account

🔴 delete · destructive

Deactivate an ACME account at the CA and remove it from the cluster. Nodes using it can no longer order or renew certificates. Runs as a task.

Argument	Type	Required	Description
name	string	yes	Account name
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_list_acme_directories

🟢 read

List the known ACME CA directories (Let’s Encrypt production/staging…). With directory, also fetch that CA’s metadata: terms-of-service URL (needed to register an account) and whether external account binding is required.

Argument	Type	Required	Description
directory	string		Also fetch metadata for this directory URL

proxmox_list_acme_plugins

🟢 read

List the cluster’s ACME challenge plugins (standalone HTTP and DNS API plugins). Credentials in plugin data are redacted; only their keys are shown.

Argument	Type	Required	Description
type	"dns" | "standalone"		Only plugins of this type

proxmox_get_acme_plugin

🟢 read

Get one ACME challenge plugin’s configuration (DNS API, nodes, validation delay). Credential values are redacted.

Argument	Type	Required	Description
id	string	yes	Plugin ID

proxmox_get_acme_challenge_schema

🟢 read

Show which credential fields each ACME DNS API plugin needs (e.g. CF_Token for Cloudflare), to fill data in proxmox_save_acme_plugin. Filter by api name.

Argument	Type	Required	Description
api	string		Only this DNS API, e.g. cf, ovh, hetzner, route53 is ‘aws’

proxmox_save_acme_plugin

🟠 write

Create (create=true) or update an ACME challenge plugin. For DNS validation give api (e.g. cf) and data with the API credentials as key/value pairs (see proxmox_get_acme_challenge_schema); they are base64-encoded for Proxmox and never echoed back. On update, data replaces all existing credentials.

Argument	Type	Required	Description
id	string	yes	Plugin ID, e.g. cloudflare
create	boolean		Create a new plugin (default false = update)
type	"dns" | "standalone"		Challenge type (create only; default dns)
api	string		DNS API plugin name, e.g. cf, ovh, hetzner, aws, gcloud, desec
data	object		DNS API credentials, e.g. {“CF_Token”: “…”, “CF_Account_ID”: “…”}
nodes	string[]		Restrict the plugin to these nodes (default all)
validation_delay	integer		Seconds to wait before validation, for slow DNS propagation (default 30)
disable	boolean		Disable the plugin
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_delete_acme_plugin

🔴 delete · destructive

Delete an ACME challenge plugin. Node certificate domains that use it can no longer be validated.

Argument	Type	Required	Description
id	string	yes	Plugin ID

vms

QEMU virtual machines: status, configuration, power, create, clone, disks, migration, templates, cloud-init and statistics.

Tool	Access	Summary
proxmox_list_vms	🟢 read	List VMs with live details
proxmox_get_vm	🟢 read	Get VM details
proxmox_get_vm_config	🟢 read	Get VM configuration
proxmox_get_vm_stats	🟢 read	Get VM performance history
proxmox_get_vm_cloudinit	🟢 read	Get VM cloud-init data
proxmox_check_vm_migration	🟢 read	Check VM migration preconditions
proxmox_check_vm_feature	🟢 read	Check VM feature support
proxmox_vm_power	🟠 write	Start, stop or reboot a VM
proxmox_create_vm	🟠 write	Create a VM
proxmox_clone_vm	🟠 write	Clone a VM or template
proxmox_update_vm_config	🟠 write	Update VM configuration
proxmox_resize_vm_disk	🟠 write	Grow a VM disk
proxmox_move_vm_disk	🟠 write	Move a VM disk
proxmox_unlink_vm_disk	🔴 delete	Detach or delete VM disks
proxmox_migrate_vm	🟠 write	Migrate a VM
proxmox_convert_vm_to_template	🟠 write	Convert a VM to a template
proxmox_delete_vm	🔴 delete	Delete a VM
proxmox_regenerate_vm_cloudinit	🟠 write	Regenerate VM cloud-init drive
proxmox_send_vm_key	🟣 exec	Send keystrokes to a VM
proxmox_vm_monitor_command	🟣 exec	Run a QEMU monitor command

proxmox_list_vms

🟢 read

List QEMU VMs straight from the nodes (GET /nodes/{node}/qemu?full=1), with details proxmox_list_guests lacks: disk I/O counters, host memory, PSI pressure stalls and the running QEMU version/machine. Without node, queries every online node. For a quick cluster-wide list with filters by tag/pool use proxmox_list_guests instead.

Argument	Type	Required	Description
node	string		Only this node (default: all online nodes)
status	"running" | "stopped"		Only VMs in this state
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 500)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_vm

🟢 read

Get a VM’s live status (run state, CPU, memory, disk/network I/O, uptime, HA, lock, guest agent, QEMU version) together with a summary of its configuration (CPU, memory, disks, NICs, boot order, firmware, cloud-init, tags, notes) and any pending changes that need a restart. Use proxmox_get_vm_config for the raw config.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_vm_config

🟢 read

Get a VM’s configuration as Proxmox stores it (key → value, secrets redacted). By default pending changes are shown applied; current=true shows the running values instead, pending=true lists every key with its current and pending value, and snapshot reads the config saved in a snapshot. The digest can be passed to proxmox_update_vm_config for safe concurrent edits.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
current	boolean		Show the current (running) values instead of values with pending changes applied
pending	boolean		List each key with its current value, pending value and pending deletion
snapshot	string		Read the configuration stored in this snapshot

proxmox_get_vm_stats

🟢 read

Get a VM’s performance history from Proxmox’s RRD database: min/avg/max of CPU %, memory, network and disk throughput and pressure stalls over the last hour/day/week/month/year, plus a downsampled time series. Use for ‘was it busy?’, trend and capacity questions.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
timeframe	"hour" | "day" | "week" | "month" | "year"		Time window (default hour)
cf	"AVERAGE" | "MAX"		Consolidation function for each data point (default AVERAGE)
points	integer		Number of points in the returned series (default 12; 0 = summary only)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_vm_cloudinit

🟢 read

Show a VM’s cloud-init settings with current vs pending values (pending ones need proxmox_regenerate_vm_cloudinit or a restart to reach the guest), plus the generated user-data, network-config and meta-data as the guest will see them. Passwords are redacted.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
dump	("user" | "network" | "meta")[]		Which generated documents to include (default all three; [] for none)

proxmox_check_vm_migration

🟢 read

Check whether and where a VM can be migrated before calling proxmox_migrate_vm: allowed and blocked target nodes (with unavailable storages or blocking HA rules), local disks that would need with_local_disks/targetstorage, local devices (PCI/USB passthrough) that block migration, and mapped resources.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
target	string		Target node to check specifically

proxmox_check_vm_feature

🟢 read

Check whether a VM’s storage supports snapshots, linked clones (‘clone’) or full copies (‘copy’), optionally for a given snapshot, and on which nodes. Useful before proxmox_clone_vm or taking snapshots.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
feature	"snapshot" | "clone" | "copy"	yes	Feature to check
snapname	string		Check for this snapshot

proxmox_vm_power

🟠 write · destructive

Change a VM’s power state. start; shutdown (clean ACPI shutdown, optionally force_stop after timeout); stop (hard power-off, may lose data); reboot (clean, applies pending config); reset (hard reset); suspend (pause in RAM); resume; hibernate (save RAM to disk and stop; resumes on next start). Reports without acting when the VM is already in the requested state.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
action	"start" | "stop" | "shutdown" | "reboot" | "reset" | "suspend" | "resume" | "hibernate"	yes	Power action
timeout	integer		Seconds to wait for start/stop/shutdown/reboot to complete
force_stop	boolean		shutdown: hard-stop the VM if it hasn’t shut down within the timeout
keep_active	boolean		stop/shutdown: don’t deactivate storage volumes
overrule_shutdown	boolean		stop: abort running shutdown tasks first
state_storage	string		hibernate: storage for the saved RAM state
machine	string		start: override the QEMU machine type for this boot
skiplock	boolean		Ignore a config lock (root@pam only; use with care)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_create_vm

🟠 write

Create a QEMU VM. Give disks as typed objects (bus, storage, size_gb, options, or import_from to import a cloud image) or raw specs, an ISO to attach as CD-ROM, NICs (default one virtio NIC on vmbr0), UEFI (bios=ovmf adds an EFI disk) and TPM, and cloud-init settings (setting cloudinit_storage adds the cloud-init drive). VMID defaults to the next free one. Anything else can go in extra with Proxmox’s parameter names (e.g. hostpci0, serial0, args). To copy an existing VM or template use proxmox_clone_vm; to restore a backup use the backup tools.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
vmid	integer		VMID for the new VM (default: next free ID)
name	string		VM name (DNS-style: letters, digits, ‘-’ and ‘.’)
memory_mb	integer		Memory in MiB, e.g. 4096
balloon_mb	integer		Minimum memory for the balloon driver in MiB (0 disables ballooning)
cores	integer		CPU cores per socket
sockets	integer		CPU sockets
cpu	string		CPU type, e.g. host, x86-64-v2-AES, kvm64 (or a full cpu property string)
numa	boolean		Enable NUMA
ostype	"other" | "wxp" | "w2k" | "w2k3" | "w2k8" | "wvista" | "win7" | "win8" | "win10" | "win11" | "l24" | "l26" | "solaris"		Guest OS type: l26 = Linux 2.6+, win11/win10…, other
scsihw	"lsi" | "lsi53c810" | "virtio-scsi-pci" | "virtio-scsi-single" | "megasas" | "pvscsi"		SCSI controller model (virtio-scsi-single recommended)
bios	"seabios" | "ovmf"		Firmware: seabios (legacy BIOS) or ovmf (UEFI; needs an EFI disk)
machine	string		QEMU machine type, e.g. q35, pc, pc-q35-9.0
vga	string		Display, e.g. std, virtio, qxl, serial0, none
agent	boolean | string		QEMU guest agent: true/false, or a property string like ‘enabled=1,fstrim_cloned_disks=1’
onboot	boolean		Start the VM when the node boots
startup	string		Startup/shutdown order and delays, e.g. ‘order=2,up=30,down=60’
protection	boolean		Protect the VM and its disks from removal
tags	string[]		Tags (replaces all existing tags)
description	string		Notes shown in the VM summary (Markdown)
boot_order	string[]		Boot device order, e.g. [“scsi0”, “ide2”, “net0”]
hotplug	string		Hotplug features, e.g. ‘network,disk,usb’ or ‘0’ to disable
ciuser	string		cloud-init: user to create/configure
cipassword	string		cloud-init: password for the user (prefer sshkeys)
sshkeys	string | string[]		cloud-init: public SSH keys (OpenSSH format, one per entry or newline-separated). URL-encoded for Proxmox automatically.
ipconfig	object		cloud-init IP config per NIC index, e.g. {“0”: “ip=dhcp”, “1”: “ip=10.0.0.5/24,gw=10.0.0.1”} (ip6=auto/dhcp also allowed)
nameserver	string		cloud-init: DNS servers (space-separated)
searchdomain	string		cloud-init: DNS search domains
citype	"configdrive2" | "nocloud" | "opennebula"		cloud-init data format (default depends on ostype)
ciupgrade	boolean		cloud-init: upgrade packages on first boot (default true)
cicustom	string		cloud-init: custom snippet files, e.g. ‘user=local:snippets/user.yaml’
storage	string		Default storage for disks, EFI/TPM state and the cloud-init drive when they don’t name one, e.g. local-lvm
disks	object[]		Disks, e.g. [{bus: “scsi”, storage: “local-lvm”, size_gb: 32, options: {discard: “on”, ssd: true, iothread: true}}]
iso	string		ISO volume to attach as CD-ROM on ide2, e.g. ‘local:iso/debian-12.iso’
nets	object[]		Network interfaces net0, net1… (default one virtio NIC on vmbr0; [] for none)
efi_storage	string		Storage for the EFI vars disk (used with bios=ovmf; default storage / first disk’s storage)
efi_pre_enrolled_keys	boolean		Pre-enroll Secure Boot keys in the EFI disk (needed for Windows 11 Secure Boot)
tpm_storage	string		Add a TPM 2.0 state disk on this storage (needed for Windows 11)
cloudinit_storage	string		Add a cloud-init drive on this storage (ide2, or ide0 when an ISO uses ide2)
start	boolean		Start the VM after creating it
pool	string		Add the VM to this resource pool
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_clone_vm

🟠 write

Copy a VM or template to a new VM. Templates get a fast linked clone by default (full=true for an independent copy); normal VMs are always copied in full. newid defaults to the next free VMID. target (another node) only works when the source disks are on shared storage. Clone from a snapshot with snapname. Use proxmox_check_vm_feature feature=clone to see if linked clones are possible.

Argument	Type	Required	Description
vmid	integer	yes	Source VM or template ID
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
newid	integer		VMID for the clone (default: next free ID)
name	string		Name for the clone
full	boolean		Full copy instead of a linked clone (templates only; normal VMs are always full; implied by storage/format)
target	string		Node to create the clone on (source must be on shared storage)
storage	string		Target storage for a full clone
format	"raw" | "qcow2" | "vmdk"		Disk format for a full clone
pool	string		Add the clone to this pool
description	string		Notes for the clone
snapname	string		Clone from this snapshot
bwlimit	integer		I/O bandwidth limit in KiB/s
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_update_vm_config

🟠 write · destructive

Change a VM’s settings; only the given fields change. Common fields are typed; for disks, NICs and devices use extra with Proxmox keys, e.g. {scsi1: “local-lvm:20,ssd=1”} (adds a new 20 GiB disk), {net1: “virtio,bridge=vmbr1”}, {hostpci0: “0000:01:00.0”}. On a running VM, changes that can’t be hot-plugged (e.g. CPU type, memory without hotplug) become pending until the next reboot; the result lists them. delete removes keys (deleting a disk key only detaches it to unusedN, but deleting an unusedN key destroys that volume and needs delete permission; proxmox_unlink_vm_disk is the explicit way to destroy disks). revert drops pending changes. Use proxmox_resize_vm_disk to grow disks.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
name	string		VM name (DNS-style: letters, digits, ‘-’ and ‘.’)
memory_mb	integer		Memory in MiB, e.g. 4096
balloon_mb	integer		Minimum memory for the balloon driver in MiB (0 disables ballooning)
cores	integer		CPU cores per socket
sockets	integer		CPU sockets
cpu	string		CPU type, e.g. host, x86-64-v2-AES, kvm64 (or a full cpu property string)
numa	boolean		Enable NUMA
ostype	"other" | "wxp" | "w2k" | "w2k3" | "w2k8" | "wvista" | "win7" | "win8" | "win10" | "win11" | "l24" | "l26" | "solaris"		Guest OS type: l26 = Linux 2.6+, win11/win10…, other
scsihw	"lsi" | "lsi53c810" | "virtio-scsi-pci" | "virtio-scsi-single" | "megasas" | "pvscsi"		SCSI controller model (virtio-scsi-single recommended)
bios	"seabios" | "ovmf"		Firmware: seabios (legacy BIOS) or ovmf (UEFI; needs an EFI disk)
machine	string		QEMU machine type, e.g. q35, pc, pc-q35-9.0
vga	string		Display, e.g. std, virtio, qxl, serial0, none
agent	boolean | string		QEMU guest agent: true/false, or a property string like ‘enabled=1,fstrim_cloned_disks=1’
onboot	boolean		Start the VM when the node boots
startup	string		Startup/shutdown order and delays, e.g. ‘order=2,up=30,down=60’
protection	boolean		Protect the VM and its disks from removal
tags	string[]		Tags (replaces all existing tags)
description	string		Notes shown in the VM summary (Markdown)
boot_order	string[]		Boot device order, e.g. [“scsi0”, “ide2”, “net0”]
hotplug	string		Hotplug features, e.g. ‘network,disk,usb’ or ‘0’ to disable
ciuser	string		cloud-init: user to create/configure
cipassword	string		cloud-init: password for the user (prefer sshkeys)
sshkeys	string | string[]		cloud-init: public SSH keys (OpenSSH format, one per entry or newline-separated). URL-encoded for Proxmox automatically.
ipconfig	object		cloud-init IP config per NIC index, e.g. {“0”: “ip=dhcp”, “1”: “ip=10.0.0.5/24,gw=10.0.0.1”} (ip6=auto/dhcp also allowed)
nameserver	string		cloud-init: DNS servers (space-separated)
searchdomain	string		cloud-init: DNS search domains
citype	"configdrive2" | "nocloud" | "opennebula"		cloud-init data format (default depends on ostype)
ciupgrade	boolean		cloud-init: upgrade packages on first boot (default true)
cicustom	string		cloud-init: custom snippet files, e.g. ‘user=local:snippets/user.yaml’
vcpus	integer		Number of hot-plugged vCPUs (≤ sockets×cores)
cpulimit	number		CPU usage limit in cores (0 = unlimited)
cpuunits	integer		CPU scheduler weight
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
revert	string[]		Pending changes to revert, by key
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
skiplock	boolean		Ignore a config lock (root@pam only; use with care)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_resize_vm_disk

🟠 write

Grow a VM disk, e.g. size=‘+10G’ to add 10 GiB or ‘64G’ for an absolute size. Disks can’t be shrunk. Works on running VMs; the partition and filesystem inside the guest still need extending afterwards.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
disk	string	yes	Disk key, e.g. scsi0, virtio1, sata0
size	string	yes	New size (‘64G’) or increment (‘+10G’); units K, M, G, T
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
skiplock	boolean		Ignore a config lock (root@pam only; use with care)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_move_vm_disk

🟠 write · destructive

Move a VM disk to another storage (works live on running VMs) or reassign it to another VM (target_vmid, optionally target_disk). After a storage move the old copy is kept as an unused disk unless delete_source=true.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
disk	string	yes	Disk key, e.g. scsi0, virtio1, sata0
storage	string		Target storage
format	"raw" | "qcow2" | "vmdk"		Target format (storage moves only)
delete_source	boolean		Delete the original disk after a successful copy (default keep it as unusedN)
target_vmid	integer		Reassign the disk to this VM instead (same node)
target_disk	string		Disk key on the target VM (default: same key)
bwlimit	integer		I/O bandwidth limit in KiB/s
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
target_digest	string		Only proceed if the target VM’s config digest matches
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_unlink_vm_disk

🔴 delete · destructive

Remove disks from a VM. Without destroy, disks are detached and kept as unusedN entries (data intact, re-attachable via proxmox_update_vm_config). With destroy=true the volumes are permanently deleted. Also deletes unusedN entries’ volumes when given with destroy=true.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
disks	string[]	yes	Disk keys to remove, e.g. [“scsi1”, “unused0”]
destroy	boolean		Permanently delete the disk images (default false: detach to unusedN)

proxmox_migrate_vm

🟠 write · destructive

Move a VM to another node in the cluster. Running VMs are live-migrated (online defaults to true when running). VMs with local disks need with_local_disks=true (optionally targetstorage). Check first with proxmox_check_vm_migration.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
target	string	yes	Target node
online	boolean		Live-migrate a running VM (default true when running)
with_local_disks	boolean		Also migrate local disks (live storage migration)
targetstorage	string		Target storage, or a mapping ‘src:dst,src2:dst2’ (with local disks)
migration_type	"secure" | "insecure"		insecure skips the SSH tunnel (trusted networks only)
migration_network	string		CIDR of the network to migrate over
bwlimit	integer		Bandwidth limit in KiB/s
with_conntrack_state	boolean		Also migrate firewall conntrack entries (running VMs)
force	boolean		Allow migrating VMs with local devices (root only)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_convert_vm_to_template

🟠 write · destructive

Turn a stopped VM into a template (irreversible: templates can’t be started, only cloned with proxmox_clone_vm). Its disks become read-only base images.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
disk	string		Convert only this disk to a base image
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_delete_vm

🔴 delete · destructive

Permanently destroy a VM and all its disks. Refuses a running VM unless stop=true (hard-stops it first). purge=true also removes it from backup/replication jobs and HA; destroy_unreferenced_disks=true also deletes orphaned disks carrying its VMID.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
stop	boolean		Hard-stop the VM first if it is running
purge	boolean		Also remove the VMID from backup jobs, replication jobs and HA
destroy_unreferenced_disks	boolean		Also destroy disks with this VMID not referenced in the config
skiplock	boolean		Ignore a config lock (root@pam only; use with care)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_regenerate_vm_cloudinit

🟠 write

Rebuild a VM’s cloud-init drive from its current settings so pending cloud-init changes (user, keys, IPs, DNS) reach the guest. The guest applies them on its next boot (cloud-init normally runs per instance).

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.

proxmox_send_vm_key

🟣 exec · destructive

Press keys on a VM’s virtual keyboard, as on its console: special keys/combos with keys (QEMU names, e.g. ‘ctrl-alt-delete’, ‘ret’, ‘esc’, ‘tab’, ‘f2’, ‘up’, ‘alt-f4’) and/or type ASCII text (US layout, ‘\n’ presses Enter). Useful for boot menus, installers or a hung login prompt. Keys are sent one at a time; nothing is read back.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
keys	string[]		Key names sent before text
text	string		Text to type (ASCII, US keyboard layout)
skiplock	boolean		Ignore a config lock (root@pam only; use with care)

proxmox_vm_monitor_command

🟣 exec · destructive

Run a QEMU human monitor (HMP) command on a running VM and return its output, e.g. ‘info status’, ‘info block’, ‘info network’, ‘info cpus’, ‘info balloon’, ‘info migrate’. Non-info commands (e.g. ‘balloon 2048’, ‘device_del’) change the live VM; prefer the dedicated tools where they exist.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
command	string	yes	Monitor command, e.g. ‘info block’

containers

LXC containers: status, configuration, power, create, clone, volumes, migration, templates, interfaces and statistics.

Tool	Access	Summary
proxmox_list_containers	🟢 read	List containers
proxmox_get_container	🟢 read	Get container details
proxmox_get_container_config	🟢 read	Get container configuration
proxmox_get_container_interfaces	🟢 read	Get container IP addresses
proxmox_get_container_stats	🟢 read	Get container performance history
proxmox_check_container_feature	🟢 read	Check container feature support
proxmox_check_container_migration	🟢 read	Check container migration preconditions
proxmox_container_power	🟠 write	Start, stop or reboot a container
proxmox_create_container	🟠 write	Create a container
proxmox_clone_container	🟠 write	Clone a container
proxmox_update_container_config	🟠 write	Update container configuration
proxmox_resize_container_disk	🟠 write	Resize a container disk
proxmox_move_container_volume	🟠 write	Move a container volume
proxmox_migrate_container	🟠 write	Migrate a container
proxmox_convert_container_to_template	🟠 write	Convert a container to a template
proxmox_delete_container	🔴 delete	Delete a container

proxmox_list_containers

🟢 read

List LXC containers across the cluster with status, node, CPU, memory, disk, uptime, tags and pool. For VMs and containers together use proxmox_list_guests.

Argument	Type	Required	Description
node	string		Only containers on this node
status	"running" | "stopped"		Only containers in this state
templates	"include" | "exclude" | "only"		How to treat templates (default include)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 500)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_container

🟢 read

Get an LXC container’s live status (CPU, memory, swap, rootfs usage, uptime) together with a summary of its configuration: hostname, OS, cores, memory, swap, rootfs and mount points, network interfaces with configured IPs, live IP addresses (when running), features, unprivileged, onboot, tags and pending changes that apply on next restart. Use proxmox_get_container_config for the full raw config.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.

proxmox_get_container_config

🟢 read

Get an LXC container’s full configuration as stored by Proxmox (secrets redacted). Options: current=true for the running values instead of pending ones, snapshot to read the config as saved in a snapshot, or pending=true to list each key with its current and pending value. The returned digest can be passed to proxmox_update_container_config for optimistic locking.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
current	boolean		Return current values instead of values including pending changes
snapshot	string		Read the config saved in this snapshot
pending	boolean		Return the key/current/pending listing from the pending endpoint instead

proxmox_get_container_interfaces

🟢 read

Get the live network interfaces and IP addresses (IPv4 and IPv6) inside a running LXC container, including addresses obtained via DHCP/SLAAC that the config doesn’t show. The container must be running.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_container_stats

🟢 read

Summarize an LXC container’s performance history from RRD data: average, maximum and latest CPU %, memory, swap, disk usage, network and disk I/O rates over the chosen timeframe. Set points=true to also get the individual data points.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
timeframe	"hour" | "day" | "week" | "month" | "year"		Time window (default hour)
cf	"AVERAGE" | "MAX"		RRD consolidation function (default AVERAGE)
points	boolean		Also return the data points (compacted)

proxmox_check_container_feature

🟢 read

Check whether a container’s storage supports snapshots, cloning (linked) or copying (full clone), optionally from a given snapshot, and on which nodes. Useful before proxmox_create_snapshot or proxmox_clone_container.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
feature	"snapshot" | "clone" | "copy"	yes	Feature to check
snapname	string		Check from this snapshot

proxmox_check_container_migration

🟢 read

Check whether an LXC container can be migrated, and to which nodes: reports running state, local disks/mount points that block migration, and allowed/not-allowed target nodes. Call before proxmox_migrate_container.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
target	string		Target node to check

proxmox_container_power

🟠 write · destructive

Change an LXC container’s power state: start, stop (immediate, like pulling the plug), shutdown (clean, with optional timeout and force_stop), reboot (clean shutdown and start; applies pending changes), suspend or resume (experimental for containers). Returns once the task finishes unless wait=false.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
action	"start" | "stop" | "shutdown" | "reboot" | "suspend" | "resume"	yes	Power action
timeout	integer		Seconds to wait for a clean shutdown (shutdown/reboot; Proxmox default 60)
force_stop	boolean		Hard-stop if the clean shutdown doesn’t finish within the timeout (shutdown only)
overrule_shutdown	boolean		Abort a running shutdown task before stopping (stop only)
skiplock	boolean		Ignore locks (start/stop; root only)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_create_container

🟠 write

Create an LXC container from an OS template (a vztmpl volume such as local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst; list a storage’s vztmpl content to find one). The VMID defaults to the next free ID. The root disk is allocated on rootfs_storage (default size 8 GiB). Without nets one interface eth0 on vmbr0 with DHCP is added; pass nets: [] for none. A new interface defaults to ip=dhcp unless ip or ip6 is given. Set password and/or ssh_public_keys for root access. Unprivileged containers are the Proxmox default for new containers; features.nesting is recommended for systemd-based distros. Anything else via extra (e.g. dev0, cpulimit; hookscript needs exec permission).

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
vmid	integer		VMID for the new container (default: next free ID)
ostemplate	string	yes	OS template volume, e.g. local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst
hostname	string		Hostname
password	string		Root password inside the container
ssh_public_keys	string		Root’s authorized SSH public keys (OpenSSH format, one per line)
rootfs_storage	string		Storage for the root disk, e.g. local-lvm (default: Proxmox’s default storage local)
rootfs_size_gb	number		Root disk size in GiB (default 8)
mount_points	object[]		Additional mount points, assigned to mp0, mp1… in order
nets	object[]		Network interfaces, assigned to net0, net1… in order
cores	integer		CPU cores (default: all host cores)
memory	integer		Memory in MiB (default 512)
swap	integer		Swap in MiB (default 512)
unprivileged	boolean		Run as an unprivileged container (recommended; Proxmox default for new containers)
features	object		Container features; booleans set to false are written as 0
ostype	string		OS type (normally detected from the template), e.g. debian, ubuntu, alpine
arch	"amd64" | "i386" | "arm64" | "armhf" | "riscv32" | "riscv64"		Architecture (default amd64)
nameserver	string		DNS server(s), space-separated (default: copied from the host)
searchdomain	string		DNS search domain(s) (default: copied from the host)
timezone	string		Time zone, e.g. Europe/London, or “host”
onboot	boolean		Start when the node boots
start	boolean		Start the container once created
protection	boolean		Protect against removal
pool	string		Add to this resource pool
tags	string[]		Tags, e.g. [“prod”, “dns”] (replaces existing tags)
description	string		Notes shown in the container’s summary
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_clone_container

🟠 write

Clone an LXC container or container template to a new VMID (default: next free ID). Templates get a linked clone unless full=true; normal containers are always fully copied (stop the source, or clone from a snapshot with snapname, since a running container can’t be copied directly). storage sets the target storage for full clones; target places the clone on another node (shared storage only).

Argument	Type	Required	Description
vmid	integer	yes	Source container ID
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
newid	integer		VMID for the clone (default: next free ID)
hostname	string		Hostname of the clone
description	string		Notes for the clone
full	boolean		Full copy instead of a linked clone (templates only; default linked unless storage is given)
storage	string		Target storage for a full clone
target	string		Target node (source must be on shared storage)
pool	string		Add the clone to this pool
snapname	string		Clone from this snapshot
bwlimit	number		I/O bandwidth limit in KiB/s
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_update_container_config

🟠 write · destructive

Change an LXC container’s configuration; only the given fields change. nets and mount_points are keyed by netN/mpN and merged with the existing entry (e.g. {“net0”: {“ip”: “10.0.0.5/24”, “gw”: “10.0.0.1”}} keeps the bridge and MAC); features is merged too. New mount points with storage+size_gb are allocated. Memory, swap, cores and network changes usually apply live; others become pending until a reboot (see pending_changes in the result). Use delete to remove keys (removing an mpN volume keeps it as unusedN; deleting an unusedN key destroys the volume and needs delete permission), revert to discard pending changes, extra for anything else. To grow a disk use proxmox_resize_container_disk.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
hostname	string		Hostname
cores	integer		CPU cores
cpulimit	number		CPU time limit (0 = unlimited; 2 = two cores’ worth)
cpuunits	integer		CPU weight relative to other guests
memory	integer		Memory in MiB
swap	integer		Swap in MiB
nets	object		Network interfaces to add or change, keyed by net0, net1…
mount_points	object		Mount points to add or change, keyed by mp0, mp1…
features	object		Container features; booleans set to false are written as 0
nameserver	string		DNS server(s)
searchdomain	string		DNS search domain(s)
timezone	string		Time zone or “host”
onboot	boolean		Start when the node boots
startup	string		Startup order/delays, e.g. “order=2,up=30”
protection	boolean		Protect against removal
tags	string[]		Tags, e.g. [“prod”, “dns”] (replaces existing tags)
description	string		Notes
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
revert	string[]		Pending changes to discard, by key
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_resize_container_disk

🟠 write

Grow a container’s rootfs or mount point volume. size is absolute (“20G”) or relative (“+5G”). Shrinking is not supported. The filesystem is grown automatically, also while running.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
disk	string	yes	Container volume: rootfs or a mount point key such as mp0
size	string	yes	New size, e.g. “20G”, or an increase such as “+5G”
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_move_container_volume

🟠 write · destructive

Move a container’s rootfs or mount point to another storage (storage), or reassign a volume to another container (target_vmid, optional target_volume). The container usually must be stopped to move rootfs. By default the original is kept as an unusedN entry; delete_source=true removes it after a successful copy.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
volume	string	yes	Volume to move: rootfs, mpN or unusedN
storage	string		Target storage
target_vmid	integer		Reassign the volume to this container instead
target_volume	string		Config key on the target container (default: same key)
delete_source	boolean		Delete the original volume after copying (default false: kept as unused)
bwlimit	number		I/O bandwidth limit in KiB/s
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
target_digest	string		Only proceed if the target container’s config digest matches
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_migrate_container

🟠 write · destructive

Move an LXC container to another node. Containers can’t be live-migrated: a running container needs restart=true (it is shut down, moved and started again on the target, with brief downtime). Stopped containers move offline. Check first with proxmox_check_container_migration. target_storage maps local volumes to storage on the target.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
target	string	yes	Target node
restart	boolean		Restart migration for a running container (required if running)
timeout	integer		Shutdown timeout in seconds for restart migration (default 180)
target_storage	string		Target storage, or a mapping like “local-lvm:fast,local:local”
bwlimit	number		I/O bandwidth limit in KiB/s
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_convert_container_to_template

🟠 write · destructive

Turn a stopped LXC container into a template for proxmox_clone_container. This cannot be undone: templates can’t be started or edited like normal containers.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.

proxmox_delete_container

🔴 delete · destructive

Permanently destroy an LXC container and all its volumes. It must be stopped unless force=true. purge also removes it from backup jobs, replication and HA. Cannot be undone; consider a backup first.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
purge	boolean		Also remove from backup jobs, replication jobs and HA
destroy_unreferenced_disks	boolean		Also destroy disks with this VMID on any storage that aren’t in the config
force	boolean		Destroy even if running
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

agent

The QEMU guest agent: OS, network and filesystem information from inside VMs, filesystem freeze/trim, and (with exec enabled) running commands and reading/writing files.

Tool	Access	Summary
proxmox_get_guest_info	🟢 read	Get guest OS info (agent)
proxmox_get_guest_network	🟢 read	Get guest network interfaces (agent)
proxmox_get_guest_filesystems	🟢 read	Get guest filesystems (agent)
proxmox_get_guest_users	🟢 read	Get logged-in guest users (agent)
proxmox_get_guest_memory_blocks	🟢 read	Get guest memory blocks (agent)
proxmox_guest_fs_freeze	🟠 write	Freeze/thaw guest filesystems (agent)
proxmox_guest_fstrim	🟠 write	Trim guest filesystems (agent)
proxmox_guest_power	🟠 write	Shut down/suspend via agent
proxmox_guest_exec	🟣 exec	Run a command in a VM (agent)
proxmox_get_guest_exec_status	🟣 exec	Get guest command result (agent)
proxmox_guest_read_file	🟣 exec	Read a file in a VM (agent)
proxmox_guest_write_file	🟣 exec	Write a file in a VM (agent)
proxmox_guest_set_password	🟣 exec	Set a guest user’s password (agent)

proxmox_get_guest_info

🟢 read

Ask a running VM’s QEMU guest agent about the guest: OS name/version/kernel, hostname, timezone, guest clock (and its skew from this server), vCPUs online and the agent version with its disabled commands. VMs only (containers need no agent). Individual queries that fail are reported under errors instead of failing the call. Use proxmox_get_guest_network for IP addresses.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_guest_network

🟢 read

List a running VM’s network interfaces as seen inside the guest (via the QEMU guest agent): name, MAC, IPv4/IPv6 addresses with prefix, and traffic counters. The reliable way to find a VM’s IP address. Loopback is hidden unless include_loopback=true. VMs only; for containers use proxmox_get_container_interfaces.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
include_loopback	boolean		Include the loopback interface (default false)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_guest_filesystems

🟢 read

List a running VM’s mounted filesystems from inside the guest (QEMU guest agent get-fsinfo): mountpoint, type, used/total space and backing disks. Use it to check real disk usage inside a VM (Proxmox’s own disk figures for VMs are not filesystem usage). VMs only.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_guest_users

🟢 read

List the users currently logged in to a running VM (QEMU guest agent get-users), with domain and login time. VMs only.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.

proxmox_get_guest_memory_blocks

🟢 read

Show a running VM’s memory blocks as the guest sees them (QEMU guest agent get-memory-blocks/get-memory-block-info): block size and how many blocks/how much memory is online. Useful after memory hotplug. VMs only; not all guest OSes support it.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.

proxmox_guest_fs_freeze

🟠 write · destructive

Freeze, thaw or check the freeze state of a running VM’s filesystems through the QEMU guest agent (fsfreeze). While frozen, writes inside the guest block, so always thaw promptly. Backups and snapshots already freeze/thaw automatically when the agent is enabled; use this for external snapshotting or to recover a guest left frozen (action=status, then thaw).

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
action	"freeze" | "thaw" | "status"	yes	freeze: freeze all filesystems; thaw: unfreeze them; status: report ‘frozen’ or ‘thawed’

proxmox_guest_fstrim

🟠 write

Run fstrim inside a running VM via the QEMU guest agent so freed blocks are discarded and thin-provisioned storage can reclaim space. Needs discard enabled on the VM’s disks to have any effect on the host. Can take a while on large disks.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.

proxmox_guest_power

🟠 write · destructive

Ask the guest OS, through the QEMU guest agent, to shut down or suspend (to RAM, disk or hybrid). The request returns immediately; the guest then acts on it. Prefer proxmox_vm_power action=shutdown, which already uses the agent for shutdown when it is enabled; this is for agent-driven suspend or when you specifically want the in-guest path.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
action	"shutdown" | "suspend-ram" | "suspend-disk" | "suspend-hybrid"	yes	shutdown, suspend-ram (sleep), suspend-disk (hibernate) or suspend-hybrid

proxmox_guest_exec

🟣 exec · destructive

Run a command inside a running VM through the QEMU guest agent and wait for it (up to timeout_s) to return exit code, stdout and stderr. command is the program plus arguments with no shell: use [“/bin/sh”, “-c”, “…”] for pipes/redirection on Linux or [“cmd.exe”, “/c”, “…”] / [“powershell.exe”, “-Command”, “…”] on Windows. Runs as the agent’s user (root/SYSTEM). If it runs longer than timeout_s the pid is returned; follow up with proxmox_get_guest_exec_status. Output captured by the agent is size-limited (see the *_truncated flags).

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
command	string[]	yes	Program and arguments, e.g. [“/bin/sh”, “-c”, “df -h”] or [“systemctl”, “status”, “nginx”]
input_data	string		Data passed to the command’s standard input (max 65536 characters)
timeout_s	integer		How long to wait for the command to finish (default 30; 0 = return the pid immediately)

proxmox_get_guest_exec_status

🟣 exec

Check on a command started with proxmox_guest_exec: whether it has exited and, if so, its exit code, stdout and stderr. Note the guest agent forgets a command’s result once it has been read after it exited.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
pid	integer	yes	The pid returned by proxmox_guest_exec
wait_s	integer		Wait up to this many seconds for the command to exit (default 0: check once)

proxmox_guest_read_file

🟣 exec

Read a file from inside a running VM through the QEMU guest agent (e.g. a log or config file). Returns text by default, or base64 for binary files (encoding=base64). Reads at most count bytes from offset (Proxmox caps a read at 16 MiB); truncated: true means the end of the file was not reached, so read on with a higher offset. Gated behind exec permission because it can read any file in the guest.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
file	string	yes	Absolute path inside the guest, e.g. /etc/os-release or C:\Windows\System32\drivers\etc\hosts
offset	integer		Byte offset to start reading at (default 0)
count	integer		Maximum bytes to read (default 1048576 = 1 MiB, max 16 MiB)
encoding	"text" | "base64"		text (default) decodes the content; base64 returns it encoded, for binary files

proxmox_guest_write_file

🟣 exec · destructive

Write (create or overwrite) a file inside a running VM through the QEMU guest agent. Content is text by default; pass encoding=base64 with base64 content for binary files. Proxmox limits content to 61440 characters (about 60 KiB of text or 45 KiB of binary as base64). Overwrites the whole file without a backup; there is no append mode (read, modify and write back instead).

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
file	string	yes	Absolute path inside the guest
content	string	yes	File content (text, or base64 when encoding=base64); at most 61440 characters per call
encoding	"text" | "base64"		text (default) or base64 (content is already base64-encoded)

proxmox_guest_set_password

🟣 exec · destructive

Set the password of a user account inside a running VM through the QEMU guest agent (e.g. to regain access). The user must already exist. With crypted=true, password is an already-hashed crypt() string. For cloud-init VMs, the cipassword option is the persistent alternative.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
username	string	yes	User account inside the guest, e.g. root or Administrator
password	string	yes	The new password (or a crypt() hash with crypted=true)
crypted	boolean		The password is already a crypt() hash (default false)

snapshots

Snapshots of VMs and containers: list, create, roll back, describe and delete, plus a cluster-wide view of stale snapshots.

Tool	Access	Summary
proxmox_list_snapshots	🟢 read	List snapshots of a guest
proxmox_get_snapshot	🟢 read	Get snapshot details
proxmox_list_all_snapshots	🟢 read	List snapshots across all guests
proxmox_create_snapshot	🟠 write	Create a snapshot
proxmox_rollback_snapshot	🟠 write	Roll back to a snapshot
proxmox_update_snapshot	🟠 write	Update a snapshot description
proxmox_delete_snapshot	🔴 delete	Delete a snapshot

proxmox_list_snapshots

🟢 read

List the snapshots of a VM or container (the type is detected from the VMID): name, parent, description, creation time, age, whether RAM state was saved (VMs), and which snapshot the guest currently runs from, plus an indented tree view. For stale snapshots across all guests use proxmox_list_all_snapshots.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_snapshot

🟢 read

Get a snapshot of a VM or container: its description, time, parent, whether RAM was saved, and the guest configuration as it was at that snapshot (disks and networks summarized, secrets redacted). Useful to see what a rollback would restore.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
snapname	string	yes	Snapshot name (see proxmox_list_snapshots)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_list_all_snapshots

🟢 read

List snapshots of every VM and container in the cluster (or a filtered set), oldest first, with guest, node, time, age in days and description. Use older_than_days to find stale snapshots that hold back storage space and slow down disks. Guests whose snapshots can’t be read are reported under errors.

Argument	Type	Required	Description
older_than_days	number		Only snapshots older than this many days
node	string		Only guests on this node
type	"vm" | "container"		Only VMs or only containers
vmids	integer[]		Only these guests
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 500)

proxmox_create_snapshot

🟠 write

Take a snapshot of a VM or container (type detected from the VMID), e.g. before an upgrade. vmstate=true also saves a running VM’s RAM so a rollback resumes exactly where it was (VMs only; takes longer and uses disk space). The guest’s storage must support snapshots (e.g. LVM-thin, ZFS, Ceph, qcow2); check containers with proxmox_check_container_feature.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
snapname	string	yes	Snapshot name: starts with a letter; letters, digits, - and _ only, e.g. pre_upgrade_2026_10
description	string		Description of the snapshot
vmstate	boolean		Include RAM state (running VMs only)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_rollback_snapshot

🟠 write · destructive

Roll a VM or container back to a snapshot. Destructive: all changes since the snapshot (disk contents and config) are lost, and a running guest is stopped. start=true starts the guest afterwards; VM snapshots that include RAM resume automatically. Newer snapshots are kept, except that on ZFS storage only the most recent snapshot can be rolled back to (delete newer ones first with proxmox_delete_snapshot).

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
snapname	string	yes	Snapshot name (see proxmox_list_snapshots)
start	boolean		Start the guest after the rollback (default false)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_update_snapshot

🟠 write

Change the description of a VM or container snapshot. The snapshot’s contents can’t be changed.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
snapname	string	yes	Snapshot name (see proxmox_list_snapshots)
description	string	yes	New description (empty string clears it)

proxmox_delete_snapshot

🔴 delete · destructive

Delete a snapshot of a VM or container, merging its data so the guest’s current state is unaffected (other snapshots are kept). force=true removes it from the config even if deleting the disk snapshots fails (may leave orphaned storage snapshots).

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.
snapname	string	yes	Snapshot name (see proxmox_list_snapshots)
force	boolean		Remove from the config even if removing disk snapshots fails
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

storage

Storage definitions and usage, volumes and content, ISO/template downloads, storage discovery, physical disks, SMART, ZFS and LVM.

Tool	Access	Summary
proxmox_list_storage	🟢 read	List storage
proxmox_get_storage	🟢 read	Get storage
proxmox_save_storage	🟠 write	Create or update storage
proxmox_delete_storage	🔴 delete	Delete storage
proxmox_list_storage_content	🟢 read	List storage content
proxmox_get_volume	🟢 read	Get volume attributes
proxmox_update_volume	🟠 write	Update volume attributes
proxmox_delete_volume	🔴 delete	Delete volume
proxmox_allocate_disk	🟠 write	Allocate disk image
proxmox_download_to_storage	🟠 write	Download file to storage
proxmox_list_appliance_templates	🟢 read	List appliance templates
proxmox_download_appliance_template	🟠 write	Download appliance template
proxmox_get_storage_stats	🟢 read	Get storage usage history
proxmox_scan_storage	🟢 read	Scan for storage
proxmox_list_disks	🟢 read	List physical disks
proxmox_get_disk_smart	🟢 read	Get disk SMART data
proxmox_list_zfs_pools	🟢 read	List ZFS pools
proxmox_get_zfs_pool	🟢 read	Get ZFS pool status
proxmox_list_lvm	🟢 read	List LVM volume groups
proxmox_list_lvm_thin	🟢 read	List LVM thin pools
proxmox_list_directory_mounts	🟢 read	List directory mounts
proxmox_create_disk_storage	🟠 write	Create storage on disks
proxmox_delete_disk_storage	🔴 delete	Destroy storage on disks
proxmox_init_disk_gpt	🟠 write	Initialize disk with GPT
proxmox_wipe_disk	🔴 delete	Wipe disk

proxmox_list_storage

🟢 read

List the datacenter’s storage definitions (local dirs, LVM, ZFS, NFS, CIFS, PBS, Ceph…) with type, allowed content, shared/enabled flags, node restriction, server/path/pool details and backup retention, merged with each node’s live status and usage. Use proxmox_list_storage_content to see what’s on one.

Argument	Type	Required	Description
type	"btrfs" | "cephfs" | "cifs" | "dir" | "esxi" | "iscsi" | "iscsidirect" | "lvm" | "lvmthin" | "nfs" | "pbs" | "rbd" | "zfs" | "zfspool"		Only storage of this type
content	"images" | "rootdir" | "iso" | "vztmpl" | "backup" | "snippets" | "import"		Only storage that allows this content type
node	string		Only storage available on this node
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_storage

🟢 read

Get one storage definition (full config, secrets redacted) and its status/usage on each node. Pass node for that node’s detailed status (active, enabled, available bytes).

Argument	Type	Required	Description
storage	string	yes	Storage ID, e.g. “local” or “local-lvm” (see proxmox_list_storage)
node	string		Also fetch detailed status on this node

proxmox_save_storage

🟠 write

Create a storage definition, or update an existing one (decided by whether the storage ID exists). Typed fields cover dir, nfs, cifs, lvm, lvmthin, zfspool, pbs, cephfs, rbd and iscsi; anything else goes in extra. On update, type and location fields (path, export, share, vgname, thinpool, datastore, portal, target) can’t be changed. Use proxmox_scan_storage first to discover NFS exports, CIFS shares, PBS datastores, VGs and pools. Passwords and keys are redacted from the output.

Argument	Type	Required	Description
storage	string	yes	Storage ID to create or update, e.g. “nas-backup”
type	"btrfs" | "cephfs" | "cifs" | "dir" | "esxi" | "iscsi" | "iscsidirect" | "lvm" | "lvmthin" | "nfs" | "pbs" | "rbd" | "zfs" | "zfspool"		Storage type (required when creating)
content	("images" | "rootdir" | "iso" | "vztmpl" | "backup" | "snippets" | "import")[]		Allowed content types; images = VM disks, rootdir = container volumes
nodes	string[]		Restrict the storage to these nodes (default all nodes)
shared	boolean		Mark as shared: same content on all nodes (needed for migration without copying; e.g. for a dir on a cluster filesystem)
disable	boolean		Disable the storage
path	string		dir/btrfs: filesystem path (create only)
server	string		nfs/cifs/pbs: server name or IP
export	string		nfs: export path (create only)
share	string		cifs: share name (create only)
subdir	string		cifs/cephfs: subdirectory to mount
domain	string		cifs: SMB domain/workgroup
smbversion	"3" | "default" | "2.0" | "2.1" | "3.0" | "3.11"		cifs: SMB protocol version
options	string		nfs/cifs: mount options, e.g. “vers=4.2”
username	string		cifs/pbs: user name (pbs: user@realm or API token ID); rbd: Ceph user id
password	string		cifs/pbs: password or PBS API token secret
datastore	string		pbs: datastore name (create only)
namespace	string		pbs: namespace
fingerprint	string		pbs: server certificate SHA-256 fingerprint
encryption_key	string		pbs: client-side encryption key, or “autogen” to generate one
port	integer		pbs/esxi: non-default port
vgname	string		lvm/lvmthin: volume group name (create only)
thinpool	string		lvmthin: thin pool LV name (create only)
saferemove	boolean		lvm: zero-out data when removing LVs
pool	string		zfspool: ZFS pool/dataset, e.g. “rpool/data”; rbd: Ceph pool
blocksize	string		zfspool: block size, e.g. “16k”
sparse	boolean		zfspool: thin-provisioned (sparse) zvols
monhost	string		rbd/cephfs (external Ceph): monitor addresses
fs_name	string		cephfs: Ceph filesystem name
krbd	boolean		rbd: always use the krbd kernel module
keyring	string		rbd/cephfs (external Ceph): client keyring contents
portal	string		iscsi: portal IP or name (create only)
target	string		iscsi: target IQN (create only)
format	"raw" | "qcow2" | "subvol" | "vmdk"		Default image format
preallocation	"off" | "metadata" | "falloc" | "full"		Preallocation for raw/qcow2 images
is_mountpoint	string		dir: “yes” (or a path) if the path is an externally managed mount point; storage goes offline when not mounted
prune_backups	object		Backup retention for this storage (prune-backups), e.g. {keep_last: 3, keep_daily: 7}
max_protected_backups	integer		Maximum protected backups per guest (-1 = unlimited)
bwlimit	string		I/O bandwidth limits in KiB/s, e.g. “default=100000,restore=50000”
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_storage

🔴 delete · destructive

Remove a storage definition from the datacenter configuration. The data on the underlying disk/share is not deleted, but guests with disks on it will break. To destroy a local ZFS pool/LVM/directory and its disks use proxmox_delete_disk_storage.

Argument	Type	Required	Description
storage	string	yes	Storage ID, e.g. “local” or “local-lvm” (see proxmox_list_storage)

proxmox_list_storage_content

🟢 read

List the volumes on a storage: ISO images, container templates, backups, VM/CT disks, snippets and import files, with format, size, owner VMID, creation time, notes and protection. Filter by content type or VMID (e.g. all backups of guest 100).

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
storage	string	yes	Storage ID, e.g. “local” or “local-lvm” (see proxmox_list_storage)
content	"images" | "rootdir" | "iso" | "vztmpl" | "backup" | "snippets" | "import"		Only this content type
vmid	integer		Only volumes owned by this guest
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 500)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_volume

🟢 read

Get a volume’s attributes: path on disk, format, size, used space, notes and protection flag.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
volume	string	yes	Volume ID, e.g. “local:iso/debian-12.iso” or “local-lvm:vm-100-disk-0” (see proxmox_list_storage_content)
storage	string		Storage ID; taken from the volume ID’s prefix when omitted

proxmox_update_volume

🟠 write

Set a volume’s notes or protection flag. Protection (backups only) prevents pruning and deletion until removed.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
volume	string	yes	Volume ID, e.g. “local:iso/debian-12.iso” or “local-lvm:vm-100-disk-0” (see proxmox_list_storage_content)
storage	string		Storage ID; taken from the volume ID’s prefix when omitted
notes	string		New notes (“” clears them)
protected	boolean		Protect (true) or unprotect (false) the volume; only supported for backups

proxmox_delete_volume

🔴 delete · destructive

Permanently delete a volume (ISO, template, backup or disk image) from storage. Disks still referenced by a guest config can’t be deleted; detach them first. Protected backups must be unprotected with proxmox_update_volume.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
volume	string	yes	Volume ID, e.g. “local:iso/debian-12.iso” or “local-lvm:vm-100-disk-0” (see proxmox_list_storage_content)
storage	string		Storage ID; taken from the volume ID’s prefix when omitted
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_allocate_disk

🟠 write

Allocate a new, empty disk image on a storage, owned by a guest (it shows up as unused until attached). Most of the time adding a disk via the VM/container config tools is easier; use this for pre-allocating. Returns the new volume ID.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
storage	string	yes	Storage ID, e.g. “local” or “local-lvm” (see proxmox_list_storage)
vmid	integer	yes	Owner guest VMID
filename	string	yes	Volume name, e.g. “vm-100-disk-2” (add .qcow2/.raw on file-based storage)
size	string	yes	Size with suffix M or G (plain number = KiB), e.g. “32G”
format	"raw" | "qcow2" | "subvol" | "vmdk"		Image format (default depends on the storage)

proxmox_download_to_storage

🟠 write

Have a node download an ISO image, container template (vztmpl) or importable disk/OVA (import) from a URL straight onto a storage, optionally verifying a checksum and decompressing. Use proxmox_query_url_metadata to check the URL and file name first; for official LXC templates use proxmox_download_appliance_template.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
storage	string	yes	Storage ID, e.g. “local” or “local-lvm” (see proxmox_list_storage)
url	string	yes	URL to download
content	"iso" | "vztmpl" | "import"	yes	Content type: iso, vztmpl (container template) or import (disk images/OVA)
filename	string	yes	Target file name, e.g. “debian-12.7.0-amd64-netinst.iso” (normalized by Proxmox)
checksum	string		Expected checksum of the file
checksum_algorithm	"md5" | "sha1" | "sha224" | "sha256" | "sha384" | "sha512"		Checksum algorithm (required with checksum)
compression	string		Decompress the download with this algorithm, e.g. “zst”, “gz”, “lzo” (ISOs only)
verify_certificates	boolean		Verify the server’s TLS certificate (default true)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_list_appliance_templates

🟢 read

List the LXC container templates available for download from the Proxmox appliance index (Debian, Ubuntu, Alpine…, and TurnKey apps). Download one with proxmox_download_appliance_template. If the list is empty, the node may need pveam update.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
section	string		Only this section, e.g. “system” or “turnkeylinux”
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 200)

proxmox_download_appliance_template

🟠 write

Download an LXC template from the Proxmox appliance index onto a storage that allows vztmpl content. Template names come from proxmox_list_appliance_templates.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
storage	string	yes	Storage ID, e.g. “local” or “local-lvm” (see proxmox_list_storage)
template	string	yes	Template name, e.g. “debian-12-standard_12.7-1_amd64.tar.zst”
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_get_storage_stats

🟢 read

Summarize a storage’s usage over time from its RRD data (current, min, max, growth over the period) with a few sample points. Useful for capacity planning.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
storage	string	yes	Storage ID, e.g. “local” or “local-lvm” (see proxmox_list_storage)
timeframe	"hour" | "day" | "week" | "month" | "year"		Period (default day)
cf	"AVERAGE" | "MAX"		Consolidation function (default AVERAGE)
samples	integer		Number of evenly spaced sample points to include (default 12)

proxmox_scan_storage

🟢 read

Discover storage that can be added with proxmox_save_storage: NFS exports or CIFS shares on a server, PBS datastores, iSCSI targets on a portal, or local LVM volume groups, LVM thin pools and ZFS pools on a node.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
type	"nfs" | "cifs" | "pbs" | "iscsi" | "lvm" | "lvmthin" | "zfs"	yes	What to scan for
server	string		nfs/cifs/pbs: server name or IP
username	string		cifs/pbs: user name (pbs: user@realm or token ID; required for pbs)
password	string		cifs/pbs: password or token secret (required for pbs)
domain	string		cifs: SMB domain/workgroup
fingerprint	string		pbs: server certificate fingerprint
port	integer		pbs: port (default 8007)
portal	string		iscsi: portal IP or name, optionally with :port
vg	string		lvmthin: volume group to list thin pools of

proxmox_list_disks

🟢 read

List a node’s physical disks with device path, model, serial, size, type (ssd/hdd/nvme/usb), SMART health, wearout and what uses them (LVM, ZFS, Ceph OSD, partitions, mounted). Use type=unused to find disks free for new storage.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
type	"unused" | "journal_disks"		Only unused disks, or disks usable as Ceph journal/DB
include_partitions	boolean		Also list partitions
skip_smart	boolean		Skip SMART health checks (faster)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_disk_smart

🟢 read

Get a disk’s SMART health and attributes (ATA attribute table, or the text report for NVMe/SAS).

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
disk	string	yes	Block device path, e.g. “/dev/sdb” (see proxmox_list_disks)
health_only	boolean		Only return the overall health status
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_list_zfs_pools

🟢 read

List a node’s ZFS pools (zpools) with size, allocation, fragmentation, dedup ratio and health. Use proxmox_get_zfs_pool for the vdev tree and scrub status.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_get_zfs_pool

🟢 read

Get a zpool’s detailed status (like zpool status): state, status/action messages, last scrub/resilver, errors and the vdev tree with read/write/checksum error counters.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
name	string	yes	Pool name, e.g. “rpool”

proxmox_list_lvm

🟢 read

List a node’s LVM volume groups with size, free space and physical volumes.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_list_lvm_thin

🟢 read

List a node’s LVM thin pools with data and metadata usage. Thin pools that run out of metadata space fail badly, so watch metadata_usage.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_list_directory_mounts

🟢 read

List the directory storages Proxmox manages on a node’s disks (filesystems mounted under /mnt/pve/ via systemd mount units).

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.

proxmox_create_disk_storage

🟠 write · destructive

Create local storage on unused disks of a node: a ZFS pool (one or more devices with a RAID level), an LVM volume group, an LVM thin pool, or a formatted directory mounted at /mnt/pve/. ALL DATA ON THE DEVICES IS LOST. Find free disks with proxmox_list_disks type=unused. With add_storage the matching storage definition is added too.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
kind	"zfs" | "lvm" | "lvmthin" | "directory"	yes	What to create
name	string	yes	Name of the pool/VG/thin pool/directory (and of the storage when add_storage)
devices	string[]	yes	Block devices, e.g. [“/dev/sdb”]; several only for zfs
add_storage	boolean		Also add a storage definition for it (default false)
raidlevel	"single" | "mirror" | "raid10" | "raidz" | "raidz2" | "raidz3" | "draid" | "draid2" | "draid3"		zfs: RAID level (default single for one device, else required)
ashift	integer		zfs: sector size exponent (default 12)
compression	"on" | "off" | "gzip" | "lz4" | "lzjb" | "zle" | "zstd"		zfs: compression (default on)
draid_config	string		zfs dRAID: “data=,spares=”
filesystem	"ext4" | "xfs"		directory: filesystem (default ext4)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_delete_disk_storage

🔴 delete · destructive

Destroy a node-local ZFS pool, LVM volume group, LVM thin pool or managed directory mount. ALL DATA ON IT IS LOST. cleanup_config also removes/updates the storage definition; cleanup_disks wipes the disks for reuse.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
kind	"zfs" | "lvm" | "lvmthin" | "directory"	yes	What to destroy
name	string	yes	Pool/VG/thin pool/directory name
volume_group	string		lvmthin: the volume group the thin pool is in (required)
cleanup_config	boolean		Remove the storage definition (or this node from it)
cleanup_disks	boolean		Also wipe the underlying disks
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_init_disk_gpt

🟠 write · destructive

Write a new, empty GPT partition table to a disk so it can be used (e.g. for Ceph or manual partitioning). Existing partitions are lost.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
disk	string	yes	Block device path, e.g. “/dev/sdb” (see proxmox_list_disks)
uuid	string		UUID for the GPT table
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_wipe_disk

🔴 delete · destructive

Wipe a disk or partition (filesystem/LVM/ZFS signatures and the start of the device) so it shows as unused. All data on it is lost. Refuses disks that are in use.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
disk	string	yes	Block device path, e.g. “/dev/sdb” (see proxmox_list_disks)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

backup

vzdump backup jobs, ad-hoc backups, backup listing and verification state, restores, pruning and guests without backups.

Tool	Access	Summary
proxmox_list_backup_jobs	🟢 read	List backup jobs
proxmox_get_backup_job	🟢 read	Get backup job
proxmox_save_backup_job	🟠 write	Create or update backup job
proxmox_delete_backup_job	🔴 delete	Delete backup job
proxmox_run_backup_job	🟠 write	Run backup job now
proxmox_list_unbacked_guests	🟢 read	List guests without backup job
proxmox_backup_guests	🟠 write	Back up guests now
proxmox_list_backups	🟢 read	List backups
proxmox_get_backup_config	🟢 read	Show config inside a backup
proxmox_restore_backup	🟠 write	Restore a backup
proxmox_update_backup	🟠 write	Update backup notes/protection
proxmox_delete_backup	🔴 delete	Delete a backup
proxmox_preview_backup_prune	🟢 read	Preview backup pruning
proxmox_prune_backups	🔴 delete	Prune backups
proxmox_get_vzdump_defaults	🟢 read	Get backup defaults
proxmox_list_backup_files	🟢 read	Browse files in a PBS backup

proxmox_list_backup_jobs

🟢 read

List the cluster’s scheduled backup (vzdump) jobs: schedule, next run, enabled, target storage, mode, which guests (all/VMID list/pool, exclusions), compression and retention. See proxmox_get_backup_job for one job with the guests and disks it covers, and proxmox_list_unbacked_guests for guests no job covers.

Argument	Type	Required	Description
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_backup_job

🟢 read

Get one backup job’s settings plus the guests it currently includes and, per guest, which disks are backed up (and why others are excluded, e.g. backup=0).

Argument	Type	Required	Description
id	string	yes	Backup job ID (see proxmox_list_backup_jobs)
include_volumes	boolean		Include the covered guests and their disks (default true)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_save_backup_job

🟠 write

Create a scheduled backup job, or update an existing one when id names one. Choose guests with exactly one of vmids, all (optionally with exclude) or pool; on update, giving a new selection replaces the old one. schedule uses systemd calendar syntax, e.g. “daily”, “sat 02:00”, “mon..fri 21:30” (check with proxmox_simulate_schedule). Only given fields change on update. Run a job immediately with proxmox_run_backup_job.

Argument	Type	Required	Description
id	string		Job ID. Updates the job if it exists; otherwise creates it with this ID (auto-generated when omitted)
schedule	string		When to run, systemd calendar event, e.g. “daily”, “02:30”, “sun 01:00”
enabled	boolean		Enable or disable the job
storage	string		Target storage (must allow ‘backup’ content)
vmids	integer[]		Back up these guests
all	boolean		Back up all guests (optionally minus exclude)
exclude	integer[]		With all=true: guests to skip
pool	string		Back up all guests in this resource pool
node	string		Only run on this node (default: every node backs up its own guests)
mode	"snapshot" | "suspend" | "stop"		Backup mode: snapshot (live, default), suspend (brief pause) or stop (shuts the guest down for a consistent backup, then restarts it)
compress	"0" | "1" | "gzip" | "lzo" | "zstd"		Compression: zstd (recommended), gzip, lzo, or 0 for none. Ignored for Proxmox Backup Server storages
retention	object		Retention (prune-backups) settings, e.g. {keep_last: 3, keep_daily: 7, keep_weekly: 4}
remove_old	boolean		Prune older backups after the run according to the retention (Proxmox default true)
notes_template	string		Notes for the backup(s); may use {{cluster}}, {{guestname}}, {{node}} and {{vmid}}, e.g. “{{guestname}} before upgrade”
protected	boolean		Mark the resulting backups as protected (never pruned or deleted)
comment	string		Job description
repeat_missed	boolean		Run as soon as possible if a run was missed (e.g. the node was off)
bwlimit	integer		I/O bandwidth limit in KiB/s (0 = unlimited)
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_backup_job

🔴 delete · destructive

Delete a scheduled backup job. Existing backups are kept. To pause a job instead, use proxmox_save_backup_job with enabled=false.

Argument	Type	Required	Description
id	string	yes	Backup job ID (see proxmox_list_backup_jobs)

proxmox_run_backup_job

🟠 write · destructive

Run a scheduled backup job immediately with its own settings (storage, mode, compression, retention…), the way the scheduler would: one vzdump task per node for the guests on that node. By default waits for all tasks; with wait=false returns the task IDs. Note that with remove_old (the default) old backups are pruned per the job’s retention.

Argument	Type	Required	Description
id	string	yes	Backup job ID (see proxmox_list_backup_jobs)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_list_unbacked_guests

🟢 read

List VMs and containers that no backup job covers, with node and status. Use it to audit backup coverage; add them with proxmox_save_backup_job or back them up once with proxmox_backup_guests.

No arguments.

proxmox_backup_guests

🟠 write · destructive

Back up one or more VMs/containers now (vzdump), e.g. before an upgrade. Guests are grouped by node and one task runs per node. Defaults come from the node’s vzdump defaults and the storage. Use protected=true or notes_template to label a one-off backup, and remove_old=false to avoid pruning older backups as a side effect. Waits for completion by default (large guests can exceed the wait; follow with proxmox_get_task).

Argument	Type	Required	Description
vmids	integer[]	yes	Guests to back up, e.g. [100, 200]
storage	string		Target storage (default: from vzdump defaults, usually ‘local’)
mode	"snapshot" | "suspend" | "stop"		Backup mode: snapshot (live, default), suspend (brief pause) or stop (shuts the guest down for a consistent backup, then restarts it)
compress	"0" | "1" | "gzip" | "lzo" | "zstd"		Compression: zstd (recommended), gzip, lzo, or 0 for none. Ignored for Proxmox Backup Server storages
notes_template	string		Notes for the backup(s); may use {{cluster}}, {{guestname}}, {{node}} and {{vmid}}, e.g. “{{guestname}} before upgrade”
protected	boolean		Protect the new backups from pruning and deletion
remove_old	boolean		Prune older backups of these guests per the retention afterwards (Proxmox default true)
retention	object		Retention (prune-backups) settings, e.g. {keep_last: 3, keep_daily: 7, keep_weekly: 4}
bwlimit	integer		I/O bandwidth limit in KiB/s
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_list_backups

🟢 read

List backup archives across every storage that holds backups (local dirs, NFS/CIFS, Proxmox Backup Server…), newest first: volume ID, guest, time, size, format, notes, protection and PBS verification state. Filter by vmid, type, storage, node or age. Shared storages are listed once. Use the volid with proxmox_restore_backup, proxmox_get_backup_config, proxmox_update_backup or proxmox_delete_backup.

Argument	Type	Required	Description
vmid	integer		Only backups of this guest
type	"vm" | "container"		Only VM or only container backups
storage	string		Only this storage
node	string		Only storages on this node
older_than_days	number		Only backups older than this many days
newer_than_days	number		Only backups newer than this many days
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 100)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_backup_config

🟢 read

Show the guest configuration stored inside a backup archive (cores, memory, disks, network…) without restoring it, e.g. to check what a backup contains or which storage its disks need. Secrets are redacted.

Argument	Type	Required	Description
volid	string	yes	Backup volume ID as listed by proxmox_list_backups, e.g. local:backup/vzdump-qemu-100-2025_01_01-02_00_00.vma.zst or pbs:backup/vm/100/2025-01-01T02:00:00Z
node	string		Node to access the storage from. Needed for node-local storages present on several nodes (use the node shown by proxmox_list_backups); looked up automatically otherwise
raw	boolean		Return the config file text as stored (secrets redacted)

proxmox_restore_backup

🟠 write · destructive

Restore a VM or container backup (type detected from the archive) to a new VMID, or over an existing guest with force=true. Overwriting destroys the existing guest’s disks and config, needs delete permission, and the guest must be stopped. Use unique=true when restoring a copy alongside the original (new MAC addresses). The target node defaults to the node holding the backup’s storage; restoring from local storage only works on that node. Find a free VMID with proxmox_get_next_vmid.

Argument	Type	Required	Description
volid	string	yes	Backup volume ID as listed by proxmox_list_backups, e.g. local:backup/vzdump-qemu-100-2025_01_01-02_00_00.vma.zst or pbs:backup/vm/100/2025-01-01T02:00:00Z
vmid	integer	yes	VMID to restore to: a free one for a new guest, or the existing one with force=true
node	string		Node to restore on (default: the node holding the backup’s storage)
type	"vm" | "container"		Override the detected guest type
storage	string		Storage for the restored disks (default: as in the backup)
force	boolean		Overwrite the existing guest with this VMID (destroys its current disks)
unique	boolean		Assign new random MAC addresses (use for copies)
start	boolean		Start the guest after restoring
pool	string		Add the restored guest to this resource pool
bwlimit	integer		I/O bandwidth limit in KiB/s
live_restore	boolean		VMs only: start the VM immediately and restore in the background (PBS backups)
unprivileged	boolean		Containers only: restore as unprivileged (default: as in the backup)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_update_backup

🟠 write

Change a backup’s notes or protection flag. Protected backups are never pruned and can’t be deleted until unprotected; use it to keep a known-good backup.

Argument	Type	Required	Description
volid	string	yes	Backup volume ID as listed by proxmox_list_backups, e.g. local:backup/vzdump-qemu-100-2025_01_01-02_00_00.vma.zst or pbs:backup/vm/100/2025-01-01T02:00:00Z
node	string		Node to access the storage from. Needed for node-local storages present on several nodes (use the node shown by proxmox_list_backups); looked up automatically otherwise
notes	string		New notes (replaces existing; “” clears them)
protected	boolean		Protect (true) or unprotect (false) the backup

proxmox_delete_backup

🔴 delete · destructive

Permanently delete a backup archive. Protected backups must be unprotected first (proxmox_update_backup). Cannot be undone.

Argument	Type	Required	Description
volid	string	yes	Backup volume ID as listed by proxmox_list_backups, e.g. local:backup/vzdump-qemu-100-2025_01_01-02_00_00.vma.zst or pbs:backup/vm/100/2025-01-01T02:00:00Z
node	string		Node to access the storage from. Needed for node-local storages present on several nodes (use the node shown by proxmox_list_backups); looked up automatically otherwise
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_preview_backup_prune

🟢 read

Dry run of pruning a backup storage: shows which backups the retention rules (the storage’s own, or retention) would keep and which they would remove. Nothing is deleted; run proxmox_prune_backups with the same arguments to apply.

Argument	Type	Required	Description
storage	string	yes	Backup storage to prune
node	string		Node to access the storage from (needed for node-local storages present on several nodes)
vmid	integer		Only this guest’s backups
type	"vm" | "container"		Only VM or only container backups
retention	object		Retention to apply instead of the storage’s configured prune-backups, e.g. {keep_last: 3}

proxmox_prune_backups

🔴 delete · destructive

Delete the backups on a storage that the retention rules don’t keep (the storage’s prune-backups, or retention). Permanent; check first with proxmox_preview_backup_prune using the same arguments. Protected backups and archives with non-standard names are never removed.

Argument	Type	Required	Description
storage	string	yes	Backup storage to prune
node	string		Node to access the storage from (needed for node-local storages present on several nodes)
vmid	integer		Only this guest’s backups
type	"vm" | "container"		Only VM or only container backups
retention	object		Retention to apply instead of the storage’s configured prune-backups, e.g. {keep_last: 3}
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_get_vzdump_defaults

🟢 read

Show the vzdump defaults a node applies to backups (from /etc/vzdump.conf, merged with a storage’s settings when storage is given): default storage, mode, compression, retention, bandwidth limits and so on.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
storage	string		Include this storage’s settings (e.g. its retention)

proxmox_list_backup_files

🟢 read

Browse the files inside a Proxmox Backup Server backup (single-file restore): start at path “/” to see the archives (disk images/filesystem archives), then drill into directories. Only works for PBS storages. Opening VM disk images starts a temporary restore VM on the node and can take a while on first access.

Argument	Type	Required	Description
storage	string	yes	PBS storage ID
volid	string	yes	Backup volume ID as listed by proxmox_list_backups, e.g. local:backup/vzdump-qemu-100-2025_01_01-02_00_00.vma.zst or pbs:backup/vm/100/2025-01-01T02:00:00Z
path	string		Path to list, as shown in earlier results (default “/”)
node	string		Node to run the file restore on (default: any node with the storage)

tasks

Proxmox tasks (UPIDs): list, inspect, read logs, wait for and stop them.

Tool	Access	Summary
proxmox_list_tasks	🟢 read	List tasks
proxmox_get_task	🟢 read	Get task status
proxmox_get_task_log	🟢 read	Read task log
proxmox_wait_for_task	🟢 read	Wait for a task
proxmox_stop_task	🟠 write	Stop a task

proxmox_list_tasks

🟢 read

List Proxmox tasks (backups, migrations, starts, clones…). Without node, lists recent tasks across the whole cluster; with node, reads that node’s task history with server-side filters. Use errors=true to find failures.

Argument	Type	Required	Description
node	string		Only this node, with full history and server-side filters (default: recent tasks cluster-wide)
vmid	integer		Only tasks for this VM/container
type	string		Only this task type, e.g. vzdump, qmstart, qmigrate, vzcreate, qmclone
user	string		Only tasks started by this user, e.g. root@pam
errors	boolean		Only failed tasks
running	boolean		Only tasks that are still running
since	integer		Only tasks started after this UNIX time (node only)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 50)

proxmox_get_task

🟢 read

Get a task’s status (running/stopped), exit status and the last lines of its log.

Argument	Type	Required	Description
upid	string	yes	Task ID (UPID), e.g. UPID:pve1:000A1B2C:0123ABCD:6701F3A2:qmstart:100:root@pam:
log_lines	integer		How many trailing log lines to include (default 30)

proxmox_get_task_log

🟢 read

Read a task’s log, paging from the start (or the end with tail=true).

Argument	Type	Required	Description
upid	string	yes	Task ID (UPID), e.g. UPID:pve1:000A1B2C:0123ABCD:6701F3A2:qmstart:100:root@pam:
start	integer		First line (0-based, default 0)
limit	integer		Number of lines (default 500)
tail	boolean		Return the last limit lines instead

proxmox_wait_for_task

🟢 read

Wait until a running task finishes (or the timeout passes) and return its outcome and log tail.

Argument	Type	Required	Description
upid	string	yes	Task ID (UPID), e.g. UPID:pve1:000A1B2C:0123ABCD:6701F3A2:qmstart:100:root@pam:
timeout_s	integer		How long to wait in seconds (default PROXMOX_TASK_TIMEOUT_MS)

proxmox_stop_task

🟠 write · destructive

Abort a running task (e.g. a stuck backup or migration).

Argument	Type	Required	Description
upid	string	yes	Task ID (UPID), e.g. UPID:pve1:000A1B2C:0123ABCD:6701F3A2:qmstart:100:root@pam:

access

Users, groups, roles, ACLs, API tokens, authentication realms, effective permissions and two-factor authentication.

Tool	Access	Summary
proxmox_list_users	🟢 read	List users
proxmox_get_user	🟢 read	Get user
proxmox_save_user	🟠 write	Create or update a user
proxmox_delete_user	🔴 delete	Delete a user
proxmox_change_password	🟠 write	Change a user’s password
proxmox_list_groups	🟢 read	List groups
proxmox_get_group	🟢 read	Get group
proxmox_save_group	🟠 write	Create or update a group
proxmox_delete_group	🔴 delete	Delete a group
proxmox_list_roles	🟢 read	List roles
proxmox_get_role	🟢 read	Get role
proxmox_save_role	🟠 write	Create or update a role
proxmox_delete_role	🔴 delete	Delete a role
proxmox_list_privileges	🟢 read	List privileges
proxmox_list_acl	🟢 read	List ACL entries
proxmox_update_acl	🟠 write	Grant or revoke permissions
proxmox_get_permissions	🟢 read	Get effective permissions
proxmox_list_api_tokens	🟢 read	List API tokens
proxmox_get_api_token	🟢 read	Get API token
proxmox_create_api_token	🟠 write	Create an API token
proxmox_update_api_token	🟠 write	Update an API token
proxmox_delete_api_token	🔴 delete	Delete an API token
proxmox_list_realms	🟢 read	List realms
proxmox_get_realm	🟢 read	Get realm
proxmox_save_realm	🟠 write	Create or update a realm
proxmox_delete_realm	🔴 delete	Delete a realm
proxmox_sync_realm	🟠 write	Sync users/groups from a realm
proxmox_list_tfa	🟢 read	List TFA entries
proxmox_delete_tfa	🔴 delete	Delete a TFA entry
proxmox_unlock_tfa	🟠 write	Unlock a user’s TFA
proxmox_list_realm_sync_jobs	🟢 read	List realm sync jobs
proxmox_save_realm_sync_job	🟠 write	Create or update a realm sync job
proxmox_delete_realm_sync_job	🔴 delete	Delete a realm sync job

proxmox_list_users

🟢 read

List Proxmox users with enabled state, expiry, realm, name, email, groups, API token count and TFA lock-out state. Use proxmox_get_user for one user’s details and tokens.

Argument	Type	Required	Description
enabled	boolean		Only enabled (true) or disabled (false) users
realm	string		Only users of this realm, e.g. pve or pam
group	string		Only members of this group
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 500)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_user

🟢 read

Get one user’s configuration: enabled state, expiry, name, email, groups, comment, API tokens and TFA entries. For effective permissions use proxmox_get_permissions.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)

proxmox_save_user

🟠 write

Create (create=true) or update a Proxmox user. Only the given fields change on update. password is only accepted on create and only for the pve realm (pam users need a Linux account on every node); change existing passwords with proxmox_change_password. Groups replace the user’s groups unless append=true. Grant permissions afterwards with proxmox_update_acl.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)
create	boolean		Create a new user (default false = update an existing one)
password	string		Initial password (create only, pve realm; at least 8 characters). Never echoed back.
email	string		Email address
firstname	string		First name
lastname	string		Last name
groups	string[]		Group IDs the user belongs to (replaces the list unless append=true)
append	boolean		On update, add groups to the existing groups instead of replacing them
expire	integer | string		Expiry as UNIX seconds or an ISO date/time (e.g. 2027-01-31 or 2027-01-31T12:00:00Z); 0 = never expires
enable	boolean		Enable (true) or disable (false) the account
comment	string		Comment
keys	string		Yubico OTP key IDs for two-factor auth (legacy)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_user

🔴 delete · destructive

Delete a user, together with their API tokens and ACL entries. To only block logins, disable the user with proxmox_save_user enable=false.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)

proxmox_change_password

🟠 write · destructive

Set a new password for a pve- or pam-realm user (PUT /access/password). The password is never echoed back. Changing another user’s password needs User.Modify/Realm.AllocateUser; with ticket auth Proxmox may also require the caller’s current password as confirmation_password.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)
password	string	yes	The new password (pve realm requires at least 8 characters)
confirmation_password	string		Current password of the user making the change, if Proxmox asks for it

proxmox_list_groups

🟢 read

List user groups with their members and comments.

Argument	Type	Required	Description
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_group

🟢 read

Get a group’s members and comment.

Argument	Type	Required	Description
groupid	string	yes	Group ID (see proxmox_list_groups)

proxmox_save_group

🟠 write

Create (create=true) a user group or update its comment. Membership is managed on the user side: proxmox_save_user with groups (and append=true to add).

Argument	Type	Required	Description
groupid	string	yes	Group ID (see proxmox_list_groups)
create	boolean		Create a new group (default false = update an existing one)
comment	string		Comment

proxmox_delete_group

🔴 delete · destructive

Delete a user group (users stay; their membership and the group’s ACL entries are removed).

Argument	Type	Required	Description
groupid	string	yes	Group ID (see proxmox_list_groups)

proxmox_list_roles

🟢 read

List roles with their privileges. Built-in roles (Administrator, PVEAdmin, PVEVMAdmin, PVEAuditor, NoAccess…) are flagged builtin=true and cannot be changed. Use privileges=false for names only.

Argument	Type	Required	Description
privileges	boolean		Include each role’s privilege list (default true)
builtin	boolean		Only built-in (true) or only custom (false) roles
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_role

🟢 read

Get the privileges of one role, grouped by area (VM, Datastore, Sys…).

Argument	Type	Required	Description
roleid	string	yes	Role ID, e.g. PVEVMAdmin (see proxmox_list_roles)

proxmox_save_role

🟠 write · destructive

Create (create=true) a custom role or change its privileges. On update the privilege list replaces the current one unless append=true. See proxmox_list_privileges for valid names. Built-in roles can’t be modified.

Argument	Type	Required	Description
roleid	string	yes	Role ID, e.g. PVEVMAdmin (see proxmox_list_roles)
create	boolean		Create a new role (default false = update an existing one)
privs	string[]		Privileges, e.g. [“VM.Audit”, “VM.PowerMgmt”, “Datastore.Audit”]
append	boolean		On update, add privs to the role instead of replacing its privileges

proxmox_delete_role

🔴 delete · destructive

Delete a custom role. ACL entries using it stop granting anything. Built-in roles can’t be deleted.

Argument	Type	Required	Description
roleid	string	yes	Role ID, e.g. PVEVMAdmin (see proxmox_list_roles)

proxmox_list_privileges

🟢 read

List every privilege Proxmox knows (derived from the built-in Administrator role, which holds them all), grouped by area. Use when building a custom role with proxmox_save_role.

No arguments.

proxmox_list_acl

🟢 read

List access control entries: which role a user, group or API token has on which path (/, /vms/100, /storage/local, /pool/x, /nodes/pve1…) and whether it propagates to sub-paths. Filters combine. For what a user can effectively do, use proxmox_get_permissions.

Argument	Type	Required	Description
path	string		Only entries on this path or below it, e.g. /vms or /vms/100
user	string		Only entries for this user or API token ID (exact)
group	string		Only entries for this group
role	string		Only entries granting this role
type	"user" | "group" | "token"		Only entries of this subject type
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 1000)

proxmox_update_acl

🟠 write · destructive

Grant (default) or revoke (delete=true) roles on a path for users, groups and/or API tokens. Paths: / (everything), /vms/, /storage/, /pool/, /nodes/, /sdn/zones/, /mapping/… Note privilege-separated API tokens need their own ACL entries (tokens=[“user@realm!name”]), and their effective rights are the intersection with the user’s.

Argument	Type	Required	Description
path	string	yes	ACL path, e.g. /, /vms/100, /storage/local, /pool/dev
roles	string[]	yes	Roles to grant or revoke, e.g. [“PVEVMUser”]
users	string[]		User IDs, e.g. [“alice@pve”]
groups	string[]		Group IDs
tokens	string[]		Full API token IDs, e.g. [“alice@pve!automation”]
propagate	boolean		Inherit to sub-paths (default true)
delete	boolean		Revoke the roles instead of granting them

proxmox_get_permissions

🟢 read

Show effective privileges per path for the API token/user this server uses (default) or for another user or token. The first thing to check when a tool fails with 403 / ‘Permission check failed’: it shows exactly which privileges are held where. Use path to check a single path such as /vms/100.

Argument	Type	Required	Description
userid	string		User or full API token ID (user@realm!token) to check (default: the caller)
path	string		Only this path, e.g. /vms/100 or /storage/local

proxmox_list_api_tokens

🟢 read

List API tokens (full ID user@realm!name, privilege separation, expiry, comment) for one user, or for all users when userid is omitted. Secrets can never be read back.

Argument	Type	Required	Description
userid	string		User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_api_token

🟢 read

Get one API token’s settings (privilege separation, expiry, comment) and, when privilege-separated, its own ACL entries.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)
tokenid	string	yes	Token name (the part after ‘!’, e.g. ‘automation’ for alice@pve!automation)

proxmox_create_api_token

🟠 write

Create an API token for a user. The result contains the token SECRET, which Proxmox shows only this once: pass it on to the user to store safely. With privsep=true (default) the token has no rights until granted with proxmox_update_acl (tokens=[…]); with privsep=false it has the user’s full rights.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)
tokenid	string	yes	Token name (the part after ‘!’, e.g. ‘automation’ for alice@pve!automation)
comment	string		Comment
expire	integer | string		Expiry as UNIX seconds or an ISO date/time (e.g. 2027-01-31 or 2027-01-31T12:00:00Z); 0 = never expires
privsep	boolean		Privilege separation: restrict the token with its own ACLs (default true)

proxmox_update_api_token

🟠 write · destructive

Change an API token’s comment, expiry or privilege separation. regenerate=true issues a new secret (returned once, store it) and immediately invalidates the old one.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)
tokenid	string	yes	Token name (the part after ‘!’, e.g. ‘automation’ for alice@pve!automation)
comment	string		Comment
expire	integer | string		Expiry as UNIX seconds or an ISO date/time (e.g. 2027-01-31 or 2027-01-31T12:00:00Z); 0 = never expires
privsep	boolean		Privilege separation (true = token limited to its own ACLs)
regenerate	boolean		Generate a new secret; everything using the old one loses access
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)

proxmox_delete_api_token

🔴 delete · destructive

Delete (revoke) an API token; anything using it loses access immediately.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)
tokenid	string	yes	Token name (the part after ‘!’, e.g. ‘automation’ for alice@pve!automation)

proxmox_list_realms

🟢 read

List authentication realms (pam, pve, LDAP, Active Directory, OpenID Connect) with type, TFA provider and comment.

No arguments.

proxmox_get_realm

🟢 read

Get an authentication realm’s configuration (servers, base DN, sync options, OpenID issuer…). Bind passwords and client keys are redacted.

Argument	Type	Required	Description
realm	string	yes	Realm (authentication domain) ID, e.g. pam, pve or a configured LDAP/AD/OpenID realm (see proxmox_list_realms)

proxmox_save_realm

🟠 write · destructive

Create (create=true, with type) or update an authentication realm: LDAP/AD (server1, base_dn, user_attr, bind_dn + bind_password, mode), OpenID Connect (issuer_url, client_id, client_key, username_claim) or pam/pve (comment, default, tfa). Only the given fields change on update. Anything else via extra (e.g. group_dn, filter, sync_attributes, groups-claim). Secrets are never echoed back.

Argument	Type	Required	Description
realm	string	yes	Realm (authentication domain) ID, e.g. pam, pve or a configured LDAP/AD/OpenID realm (see proxmox_list_realms)
create	boolean		Create a new realm (default false = update)
type	"pam" | "pve" | "ldap" | "ad" | "openid"		Realm type (required when creating)
comment	string		Description shown on the login screen
default	boolean		Make this the default realm on the login screen
tfa	string		Realm-enforced TFA, e.g. ‘type=oath’ or ‘type=yubico,id=…,key=…’
server1	string		LDAP/AD server address
server2	string		Fallback LDAP/AD server
port	integer		LDAP/AD server port
mode	"ldap" | "ldaps" | "ldap+starttls"		LDAP/AD connection mode
verify	boolean		Verify the LDAP server’s TLS certificate
base_dn	string		LDAP base DN for users, e.g. ou=people,dc=example,dc=com
user_attr	string		LDAP user name attribute, e.g. uid (required for LDAP)
bind_dn	string		LDAP bind DN
bind_password	string		LDAP bind password (sent as password; never echoed)
domain	string		AD domain, e.g. example.com (required for AD)
issuer_url	string		OpenID issuer URL
client_id	string		OpenID client ID
client_key	string		OpenID client secret (never echoed)
username_claim	string		OpenID claim used for the username (create only), e.g. email or preferred_username
scopes	string		OpenID scopes (default ‘email profile’)
autocreate	boolean		Automatically create users on first login (OpenID)
sync_defaults_options	string		Default sync options, e.g. ‘scope=both,enable-new=1,remove-vanished=acl;entry’
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_realm

🔴 delete · destructive

Delete an authentication realm. Users of that realm can no longer log in (their user entries remain until deleted). pam and pve can’t be deleted.

Argument	Type	Required	Description
realm	string	yes	Realm (authentication domain) ID, e.g. pam, pve or a configured LDAP/AD/OpenID realm (see proxmox_list_realms)

proxmox_sync_realm

🟠 write · destructive

Sync users and/or groups from an LDAP, AD or OpenID realm into Proxmox. Use dry_run=true first to see what would change (in the task log). Options not given fall back to the realm’s sync-defaults-options. Synced groups are named -.

Argument	Type	Required	Description
realm	string	yes	Realm (authentication domain) ID, e.g. pam, pve or a configured LDAP/AD/OpenID realm (see proxmox_list_realms)
dry_run	boolean		Only report what would change; write nothing
scope	"users" | "groups" | "both"		What to sync
enable_new	boolean		Enable newly synced users (default true)
remove_vanished	string		What to remove for users/groups no longer in the directory: ‘none’ or a ;-list of acl, properties, entry (e.g. ‘acl;entry’)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_list_tfa

🟢 read

List users’ second factors (TOTP, WebAuthn, recovery keys, Yubico) with type, description, creation time and enabled state, plus TFA lock-outs. No secrets are returned. Unlock a locked-out user with proxmox_unlock_tfa.

Argument	Type	Required	Description
userid	string		User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)

proxmox_delete_tfa

🔴 delete · destructive

Remove one second factor from a user (e.g. a lost authenticator); get the ID from proxmox_list_tfa. Removing a user’s last factor lets them log in with the password alone.

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)
id	string	yes	TFA entry ID (from proxmox_list_tfa)
password	string		Current password of the user making the change, if Proxmox requires it

proxmox_unlock_tfa

🟠 write

Clear a user’s TFA lock-out after too many failed second-factor attempts (see totp_locked / tfa_locked_until in proxmox_list_tfa).

Argument	Type	Required	Description
userid	string	yes	User ID in name@realm form, e.g. alice@pve or root@pam (see proxmox_list_users)

proxmox_list_realm_sync_jobs

🟢 read

List scheduled realm sync jobs (periodic LDAP/AD/OpenID user and group sync) with schedule, last and next run.

No arguments.

proxmox_save_realm_sync_job

🟠 write

Create (create=true, with realm and schedule) or update a scheduled realm sync job. Check schedules with proxmox_simulate_schedule. For a one-off sync use proxmox_sync_realm.

Argument	Type	Required	Description
id	string	yes	Job ID
create	boolean		Create a new job (default false = update)
realm	string		Realm to sync (create only)
schedule	string		Calendar event, e.g. ‘daily’ or ‘sun 03:00’ (required when creating)
enabled	boolean		Whether the job runs
scope	"users" | "groups" | "both"		What to sync
enable_new	boolean		Enable newly synced users
remove_vanished	string		‘none’ or a ;-list of acl, properties, entry
comment	string		Comment
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)

proxmox_delete_realm_sync_job

🔴 delete · destructive

Delete a scheduled realm sync job (the realm and synced users stay).

Argument	Type	Required	Description
id	string	yes	Job ID

firewall

Firewall rules, options, aliases, IP sets and security groups at datacenter, node and guest level, plus the firewall log.

Tool	Access	Summary
proxmox_list_firewall_rules	🟢 read	List firewall rules
proxmox_get_firewall_rule	🟢 read	Get a firewall rule
proxmox_save_firewall_rule	🟠 write	Create, update or move a firewall rule
proxmox_delete_firewall_rule	🔴 delete	Delete a firewall rule
proxmox_get_firewall_options	🟢 read	Get firewall options
proxmox_update_firewall_options	🟠 write	Update firewall options
proxmox_list_firewall_aliases	🟢 read	List firewall aliases
proxmox_save_firewall_alias	🟠 write	Create or update a firewall alias
proxmox_delete_firewall_alias	🔴 delete	Delete a firewall alias
proxmox_list_firewall_ipsets	🟢 read	List firewall IP sets
proxmox_save_firewall_ipset	🟠 write	Create or update a firewall IP set
proxmox_delete_firewall_ipset	🔴 delete	Delete a firewall IP set
proxmox_save_ipset_entry	🟠 write	Add or update an IP set entry
proxmox_delete_ipset_entry	🔴 delete	Remove an IP set entry
proxmox_list_firewall_groups	🟢 read	List firewall security groups
proxmox_save_firewall_group	🟠 write	Create or update a security group
proxmox_delete_firewall_group	🔴 delete	Delete a security group
proxmox_get_firewall_log	🟢 read	Read the firewall log
proxmox_list_firewall_refs	🟢 read	List firewall alias/IP set references
proxmox_list_firewall_macros	🟢 read	List firewall macros
proxmox_get_guest_firewall_status	🟢 read	Get a guest’s firewall status

proxmox_list_firewall_rules

🟢 read

List the firewall rules of the datacenter (cluster), a node, a VM/container (guest) or a security group, in evaluation order (pos 0 first). Each rule has a readable one-line form like ‘IN SSH(ACCEPT) -i net0 -source +mgmt # admins’. Rules of type group pull in a security group’s rules. For ‘why can’t I reach VM X’ start with proxmox_get_guest_firewall_status.

Argument	Type	Required	Description
scope	"cluster" | "node" | "guest" | "group"		Firewall level: cluster = datacenter-wide; node = a host’s own firewall; guest = a VM or container (give vmid); group = a security group’s rules (give group). Inferred when omitted: guest if vmid is given, group if group is given, node if node is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
group	string		Security group name, for scope group (see proxmox_list_firewall_groups)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_firewall_rule

🟢 read

Get one firewall rule by position at any level (cluster, node, guest or security group), with its digest for safe updates.

Argument	Type	Required	Description
scope	"cluster" | "node" | "guest" | "group"		Firewall level: cluster = datacenter-wide; node = a host’s own firewall; guest = a VM or container (give vmid); group = a security group’s rules (give group). Inferred when omitted: guest if vmid is given, group if group is given, node if node is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
group	string		Security group name, for scope group (see proxmox_list_firewall_groups)
pos	integer	yes	Rule position (from proxmox_list_firewall_rules)

proxmox_save_firewall_rule

🟠 write · destructive

Create a firewall rule (no pos; type and action required) or update the rule at pos (only the given fields change; delete clears fields). Works at cluster, node, guest and security-group level. New rules are inserted at the top (position 0) unless insert_at is given; rules are evaluated top-down and the first match wins. Use moveto with pos to reorder. Rules only take effect where the firewall is enabled (see proxmox_get_guest_firewall_status / proxmox_update_firewall_options), and new rules are disabled unless enable=true.

Argument	Type	Required	Description
scope	"cluster" | "node" | "guest" | "group"		Firewall level: cluster = datacenter-wide; node = a host’s own firewall; guest = a VM or container (give vmid); group = a security group’s rules (give group). Inferred when omitted: guest if vmid is given, group if group is given, node if node is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
group	string		Security group name, for scope group (see proxmox_list_firewall_groups)
pos	integer		Position of the rule to update; omit to create a new rule
insert_at	integer		When creating: position to insert the new rule at (default 0 = top)
moveto	integer		With pos: move the rule to this position (applied after any field changes)
type	"in" | "out" | "forward" | "group"		Direction: in, out, forward (PVE 8.2+, nftables) or group (insert a security group; action = group name). Required when creating
action	string		ACCEPT, DROP or REJECT, or the security group name when type is group. Required when creating
macro	string		Predefined service macro, e.g. SSH, HTTP, HTTPS, DNS, Ping (see proxmox_list_firewall_macros). Replaces proto/dport
proto	string		IP protocol, e.g. tcp, udp, icmp, icmpv6, or a number
source	string		Source address: IP, CIDR, range, comma list, IP set (+name, +dc/name, +guest/name) or alias name (see proxmox_list_firewall_refs)
dest	string		Destination address, same syntax as source
sport	string		Source port(s): number, service name, range 1000:2000 or comma list
dport	string		Destination port(s): number, service name, range 1000:2000 or comma list
icmp_type	string		ICMP type (only with proto icmp/icmpv6), e.g. echo-request
iface	string		Interface: net0, net1… for guests; any interface name for hosts
enable	boolean		Whether the rule is active (new rules are disabled unless enable=true)
log	"emerg" | "alert" | "crit" | "err" | "warning" | "notice" | "info" | "debug" | "nolog"		Log level for packets matching this rule (nolog = off)
comment	string		Comment
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_firewall_rule

🔴 delete · destructive

Delete the firewall rule at pos (cluster, node, guest or security group). Later rules move up one position, so re-list before deleting several; pass digest to guard against concurrent edits.

Argument	Type	Required	Description
scope	"cluster" | "node" | "guest" | "group"		Firewall level: cluster = datacenter-wide; node = a host’s own firewall; guest = a VM or container (give vmid); group = a security group’s rules (give group). Inferred when omitted: guest if vmid is given, group if group is given, node if node is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
group	string		Security group name, for scope group (see proxmox_list_firewall_groups)
pos	integer	yes	Position of the rule to delete
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_get_firewall_options

🟢 read

Get firewall options for the datacenter (enable, default policies, ebtables, log rate limit), a node (enable, nftables, conntrack, synflood/smurf/tcpflags protection, log levels) or a guest (enable, policies, MAC/IP filter, DHCP, NDP, RA, log levels). effective fills in Proxmox’s defaults for unset options.

Argument	Type	Required	Description
scope	"cluster" | "node" | "guest"		Firewall level: cluster = datacenter-wide; node = a host’s own firewall; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, node if node is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest

proxmox_update_firewall_options

🟠 write · destructive

Change firewall options at datacenter (cluster), node or guest level; only the given fields change. Options differ per level: cluster: enable, policy_in, policy_out, policy_forward, ebtables, log_ratelimit; node: enable, log_level_in, log_level_out, log_level_forward, log_nf_conntrack, ndp, nf_conntrack_allow_invalid, nf_conntrack_helpers, nf_conntrack_max, nf_conntrack_tcp_timeout_established, nf_conntrack_tcp_timeout_syn_recv, nftables, nosmurfs, protection_synflood, protection_synflood_burst, protection_synflood_rate, smurf_log_level, tcp_flags_log_level, tcpflags; guest: enable, policy_in, policy_out, dhcp, ipfilter, log_level_in, log_level_out, macfilter, ndp, radv. Careful: enabling the datacenter firewall with policy_in DROP blocks everything not allowed by rules, including the web UI/SSH from networks outside the management IP set.

Argument	Type	Required	Description
scope	"cluster" | "node" | "guest"		Firewall level: cluster = datacenter-wide; node = a host’s own firewall; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, node if node is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
enable	boolean		Enable the firewall at this level (datacenter: the master switch for everything)
policy_in	"ACCEPT" | "REJECT" | "DROP"		Default inbound policy (cluster, guest)
policy_out	"ACCEPT" | "REJECT" | "DROP"		Default outbound policy (cluster, guest)
policy_forward	"ACCEPT" | "DROP"		Default forward policy (cluster; nftables)
ebtables	boolean		Enable ebtables rules cluster wide (cluster)
log_ratelimit	string		Log rate limit, e.g. ‘enable=1,rate=1/second,burst=5’ (cluster)
log_level_in	"emerg" | "alert" | "crit" | "err" | "warning" | "notice" | "info" | "debug" | "nolog"		Log level for incoming traffic (node, guest) (nolog = off)
log_level_out	"emerg" | "alert" | "crit" | "err" | "warning" | "notice" | "info" | "debug" | "nolog"		Log level for outgoing traffic (node, guest) (nolog = off)
log_level_forward	"emerg" | "alert" | "crit" | "err" | "warning" | "notice" | "info" | "debug" | "nolog"		Log level for forwarded traffic (node) (nolog = off)
nftables	boolean		Use the nftables-based proxmox-firewall (node)
ndp	boolean		Allow NDP / IPv6 neighbor discovery (node, guest)
tcpflags	boolean		Filter illegal TCP flag combinations (node)
tcp_flags_log_level	"emerg" | "alert" | "crit" | "err" | "warning" | "notice" | "info" | "debug" | "nolog"		Log level for the illegal TCP flags filter (node) (nolog = off)
nosmurfs	boolean		Enable the SMURFS filter (node)
smurf_log_level	"emerg" | "alert" | "crit" | "err" | "warning" | "notice" | "info" | "debug" | "nolog"		Log level for the SMURFS filter (node) (nolog = off)
log_nf_conntrack	boolean		Log conntrack information (node)
nf_conntrack_allow_invalid	boolean		Allow invalid packets on connection tracking (node)
nf_conntrack_helpers	string		Conntrack helpers, e.g. ‘ftp,tftp’ (node)
nf_conntrack_max	integer		Maximum tracked connections (node)
nf_conntrack_tcp_timeout_established	integer		Conntrack established timeout in seconds (node)
nf_conntrack_tcp_timeout_syn_recv	integer		Conntrack SYN-RECV timeout in seconds (node)
protection_synflood	boolean		Enable SYN flood protection (node)
protection_synflood_rate	integer		SYN flood rate limit, SYN/s per source IP (node)
protection_synflood_burst	integer		SYN flood burst per source IP (node)
dhcp	boolean		Allow DHCP (guest)
macfilter	boolean		MAC address filter: drop traffic from MACs other than the NIC’s (guest)
ipfilter	boolean		IP filter: only allow the guest’s own IPs (ipfilter-netX IP sets / link-local) (guest)
radv	boolean		Allow the guest to send IPv6 router advertisements (guest)
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_list_firewall_aliases

🟢 read

List IP/network aliases defined at datacenter (cluster) or guest level. Aliases are named addresses usable in rule source/dest.

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_save_firewall_alias

🟠 write

Create an IP/network alias, or update it if it already exists (cidr/comment; new_name renames it). Datacenter (cluster) or guest level. Rules referencing a renamed alias are not rewritten.

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
name	string	yes	Alias name
cidr	string		IP address or network in CIDR form, e.g. 10.0.0.5 or 10.0.0.0/24 (required when creating)
comment	string		Comment
new_name	string		Rename the existing alias to this
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_delete_firewall_alias

🔴 delete · destructive

Delete an IP/network alias at datacenter (cluster) or guest level. Fails while rules still reference it.

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
name	string	yes	Alias name
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_list_firewall_ipsets

🟢 read

List IP sets at datacenter (cluster) or guest level with their entries (CIDRs, nomatch exclusions, comments). Reference them in rules as +name (or +dc/name, +guest/name). Special sets: ‘management’ (hosts allowed to reach the web UI/SSH when the firewall is on), ‘blacklist’, and per-NIC ‘ipfilter-netX’ on guests.

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
name	string		Only this IP set
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_save_firewall_ipset

🟠 write

Create an IP set, or update an existing one’s comment / rename it (new_name). Datacenter (cluster) or guest level. Add entries with proxmox_save_ipset_entry.

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
name	string	yes	IP set name
comment	string		Comment
new_name	string		Rename the existing IP set to this
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_delete_firewall_ipset

🔴 delete · destructive

Delete an IP set at datacenter (cluster) or guest level. Fails if it still has entries unless force=true.

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
name	string	yes	IP set name
force	boolean		Also delete all its entries

proxmox_save_ipset_entry

🟠 write

Add an IP/network to an IP set, or update an existing entry’s comment/nomatch flag. nomatch=true makes the entry an exclusion. Datacenter (cluster) or guest level.

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
ipset	string	yes	IP set name
cidr	string	yes	IP, network in CIDR form, or alias name, e.g. 10.0.0.0/24
comment	string		Comment
nomatch	boolean		Exclude this address from the set instead of including it
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_delete_ipset_entry

🔴 delete · destructive

Remove an IP/network from an IP set at datacenter (cluster) or guest level.

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
ipset	string	yes	IP set name
cidr	string	yes	The entry to remove, exactly as listed, e.g. 10.0.0.0/24
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_list_firewall_groups

🟢 read

List the datacenter’s security groups (reusable rule sets) with their comment and rule count. See a group’s rules with proxmox_list_firewall_rules scope=group; apply a group to a guest/node with a rule of type group.

Argument	Type	Required	Description
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_save_firewall_group

🟠 write

Create a datacenter security group, or update an existing one’s comment / rename it (new_name). Add rules to it with proxmox_save_firewall_rule scope=group.

Argument	Type	Required	Description
group	string	yes	Security group name (2-18 chars, letters, digits, - and _)
comment	string		Comment
new_name	string		Rename the existing group to this
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)

proxmox_delete_firewall_group

🔴 delete · destructive

Delete a datacenter security group. Proxmox refuses while the group still has rules or is referenced by rules; remove those first.

Argument	Type	Required	Description
group	string	yes	Security group name

proxmox_get_firewall_log

🟢 read

Read the firewall log of a node (all its traffic, including guests on it) or of one guest. Only packets matching rules/policies with a log level other than nolog are logged; set log_level_in on the options or log on a rule to see drops.

Argument	Type	Required	Description
scope	"node" | "guest"		Firewall level: node = a host’s own firewall; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, node if node is given, otherwise node.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
limit	integer		Maximum number of results (default 100)
start	integer		Skip this many lines (paging)
since	integer		Only entries since this UNIX time
until	integer		Only entries until this UNIX time
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_list_firewall_refs

🟢 read

List the aliases and IP sets that can be used in rule source/dest at datacenter (cluster) or guest level, with the exact reference string to use (e.g. +dc/management, dc/myalias).

Argument	Type	Required	Description
scope	"cluster" | "guest"		Firewall level: cluster = datacenter-wide; guest = a VM or container (give vmid). Inferred when omitted: guest if vmid is given, otherwise cluster.
node	string		Node name: the host for scope node (defaults to PROXMOX_DEFAULT_NODE or the only node), or the guest’s node for scope guest (looked up from vmid when omitted)
vmid	integer		VM or container ID, for scope guest
type	"alias" | "ipset"		Only aliases or only IP sets

proxmox_list_firewall_macros

🟢 read

List the predefined firewall macros (SSH, HTTP, DNS, Ceph, …) usable as a rule’s macro instead of proto/port.

Argument	Type	Required	Description
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_guest_firewall_status

🟢 read

Whole-picture firewall view for one VM/container, for questions like ‘why can’t I reach VM X’: whether the firewall is enabled at datacenter, node and guest level and on each NIC (firewall=1), the effective policies, the guest’s rules (one line each), IP/MAC filters, and plain-language findings about what is blocking or not filtering traffic.

Argument	Type	Required	Description
vmid	integer	yes	VM or container ID (VMID), e.g. 100
node	string		Node the guest is on. Looked up automatically from the VMID when omitted.

ha

High availability: status, HA resources, groups and rules, and HA-managed migration.

Tool	Access	Summary
proxmox_get_ha_status	🟢 read	Get HA status
proxmox_list_ha_resources	🟢 read	List HA resources
proxmox_get_ha_resource	🟢 read	Get an HA resource
proxmox_save_ha_resource	🟠 write	Add or update an HA resource
proxmox_delete_ha_resource	🔴 delete	Remove an HA resource
proxmox_ha_migrate	🟠 write	Migrate or relocate an HA resource
proxmox_list_ha_groups	🟢 read	List HA groups
proxmox_get_ha_group	🟢 read	Get an HA group
proxmox_save_ha_group	🟠 write	Create or update an HA group
proxmox_delete_ha_group	🔴 delete	Delete an HA group
proxmox_list_ha_rules	🟢 read	List HA rules
proxmox_get_ha_rule	🟢 read	Get an HA rule
proxmox_save_ha_rule	🟠 write	Create or update an HA rule
proxmox_delete_ha_rule	🔴 delete	Delete an HA rule
proxmox_set_ha_armed	🟠 write	Arm or disarm the HA stack

proxmox_get_ha_status

🟢 read

High-availability overview: quorum, the current CRM master, each node’s LRM state (active/idle/maintenance, last update), fencing/arming state (PVE 9.1+), and every HA-managed service with its node and state. Use proxmox_list_ha_resources for the configured settings.

Argument	Type	Required	Description
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_list_ha_resources

🟢 read

List HA-managed VMs and containers with their requested state, group, restart/relocate limits, failback, comment, guest name and current status (node and CRM state).

Argument	Type	Required	Description
type	"vm" | "ct"		Only VMs or only containers
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 500)

proxmox_get_ha_resource

🟢 read

Get one HA resource’s configuration, its current status, and the HA rules that reference it (PVE 9+).

Argument	Type	Required	Description
sid	string | integer	yes	HA resource ID like vm:100 or ct:200, or just the VMID (100) which is resolved to vm:/ct: automatically

proxmox_save_ha_resource

🟠 write · destructive

Put a VM/container under HA management, or update its HA settings if it already is (only the given fields change). state: started (keep running), stopped, disabled (stopped, no recovery), ignored (HA hands off). New resources default to state started, which starts the guest.

Argument	Type	Required	Description
sid	string | integer	yes	HA resource ID like vm:100 or ct:200, or just the VMID (100) which is resolved to vm:/ct: automatically
state	"started" | "stopped" | "enabled" | "disabled" | "ignored"		Requested state (default started)
group	string		HA group (PVE 8; replaced by node-affinity rules in PVE 9)
max_restart	integer		Restart attempts on the same node after a failed start (default 1)
max_relocate	integer		Relocation attempts to other nodes after failed restarts (default 1)
failback	boolean		Move back to the highest-priority node when it returns (PVE 9, default true)
auto_rebalance	boolean		May be moved by automatic load rebalancing (PVE 9.1+, default true)
comment	string		Description
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_ha_resource

🔴 delete · destructive

Take a VM/container out of HA management (the guest itself is untouched and keeps running). By default it is also removed from HA rules, deleting rules left empty; purge=false keeps the rules.

Argument	Type	Required	Description
sid	string | integer	yes	HA resource ID like vm:100 or ct:200, or just the VMID (100) which is resolved to vm:/ct: automatically
purge	boolean		Also remove it from HA rules (default true)

proxmox_ha_migrate

🟠 write · destructive

Ask the HA manager to move an HA-managed guest to another node. migrate = live/online migration; relocate = stop on the old node and start on the target. For HA-managed guests use this rather than the normal migrate tools. The request is queued; follow it with proxmox_get_ha_status. PVE 9 reports resources that block the move (affinity rules) or move along with it.

Argument	Type	Required	Description
sid	string | integer	yes	HA resource ID like vm:100 or ct:200, or just the VMID (100) which is resolved to vm:/ct: automatically
action	"migrate" | "relocate"	yes	migrate (online) or relocate (stop + start)
node	string	yes	Target node

proxmox_list_ha_groups

🟢 read

List HA groups (node lists with priorities, restricted, nofailback). Deprecated in PVE 9, where groups are migrated to node-affinity rules (proxmox_list_ha_rules).

No arguments.

proxmox_get_ha_group

🟢 read

Get one HA group’s configuration (PVE 8; deprecated in PVE 9 in favour of HA rules).

Argument	Type	Required	Description
group	string	yes	HA group name

proxmox_save_ha_group

🟠 write · destructive

Create an HA group or update an existing one (PVE 8; on PVE 9 use proxmox_save_ha_rule with type node-affinity). restricted: resources may only run on the group’s nodes; nofailback: don’t move back when a higher-priority node returns.

Argument	Type	Required	Description
group	string	yes	HA group name
nodes	string[]		Nodes with optional priority, e.g. [“pve1:2”, “pve2”] (required when creating)
restricted	boolean		Only run on the listed nodes
nofailback	boolean		Don’t migrate back to a higher-priority node
comment	string		Description
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_ha_group

🔴 delete · destructive

Delete an HA group (PVE 8). Fails while HA resources still use it.

Argument	Type	Required	Description
group	string	yes	HA group name

proxmox_list_ha_rules

🟢 read

List HA rules (PVE 9+): node-affinity rules (which nodes resources prefer or must run on, with priorities) and resource-affinity rules (keep resources together or apart).

Argument	Type	Required	Description
type	"node-affinity" | "resource-affinity"		Only this rule type
resource	string | integer		Only rules affecting this resource (vm:100, ct:200 or a VMID)

proxmox_get_ha_rule

🟢 read

Get one HA rule (PVE 9+) with its digest.

Argument	Type	Required	Description
rule	string	yes	HA rule ID

proxmox_save_ha_rule

🟠 write · destructive

Create or update an HA rule (PVE 9+). node-affinity: run resources on nodes (with priorities; strict=true means only those nodes; affinity negative = avoid them). resource-affinity: affinity positive keeps resources on the same node, negative keeps them on different nodes. Only the given fields change on update.

Argument	Type	Required	Description
rule	string	yes	HA rule ID
type	"node-affinity" | "resource-affinity"		Rule type (required when creating)
resources	(string | integer)[]		HA resources the rule applies to, e.g. [“vm:100”, “ct:200”] or VMIDs (required when creating)
nodes	string[]		node-affinity: nodes with optional priority, e.g. [“pve1:2”, “pve2:1”] (required when creating)
affinity	"positive" | "negative"		positive (together / on these nodes) or negative (apart / not on these nodes). Required for resource-affinity
strict	boolean		node-affinity: only ever run on the listed nodes (default false)
disable	boolean		Disable the rule without deleting it
comment	string		Description
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_ha_rule

🔴 delete · destructive

Delete an HA rule (PVE 9+). The resources it referenced stay HA-managed.

Argument	Type	Required	Description
rule	string	yes	HA rule ID

proxmox_set_ha_armed

🟠 write · destructive

Disarm the HA stack cluster-wide (releases all watchdogs, so nodes won’t self-fence; e.g. for network or switch maintenance) or re-arm it afterwards. PVE 9.1+. resource_mode for disarm: freeze (no HA commands/state changes are applied) or ignore (HA stops managing resources, which can be handled manually). Check the result with proxmox_get_ha_status.

Argument	Type	Required	Description
action	"arm" | "disarm"	yes	arm or disarm
resource_mode	"freeze" | "ignore"		How HA resources are handled while disarmed (required for disarm)

sdn

Software-defined networking: zones, VNets, subnets, controllers, IPAM and DNS, and applying pending SDN changes.

Tool	Access	Summary
proxmox_list_sdn_objects	🟢 read	List SDN objects
proxmox_get_sdn_object	🟢 read	Get an SDN object
proxmox_get_sdn_status	🟢 read	Get SDN status on nodes
proxmox_get_sdn_pending_diff	🟢 read	Preview SDN apply (dry run)
proxmox_get_sdn_ipam_status	🟢 read	List IPAM entries
proxmox_list_sdn_fabrics	🟢 read	List SDN fabrics
proxmox_list_sdn_route_policies	🟢 read	List SDN prefix lists and route maps
proxmox_save_sdn_zone	🟠 write	Create or update an SDN zone
proxmox_save_sdn_vnet	🟠 write	Create or update an SDN vnet
proxmox_save_sdn_subnet	🟠 write	Create or update an SDN subnet
proxmox_save_sdn_controller	🟠 write	Create or update an SDN controller
proxmox_save_sdn_ipam	🟠 write	Create or update an SDN IPAM
proxmox_save_sdn_dns	🟠 write	Create or update an SDN DNS plugin
proxmox_delete_sdn_object	🔴 delete	Delete an SDN object
proxmox_save_sdn_vnet_ip	🟠 write	Create or update a vnet IP mapping
proxmox_delete_sdn_vnet_ip	🔴 delete	Delete a vnet IP mapping
proxmox_apply_sdn	🟠 write	Apply SDN configuration
proxmox_rollback_sdn	🟠 write	Discard pending SDN changes

proxmox_list_sdn_objects

🟢 read

List Software-Defined Networking objects of one kind: zones, vnets, subnets of a vnet, controllers, IPAMs or DNS plugins. Use pending=true to see uncommitted changes (state new/changed/deleted). Related: proxmox_get_sdn_object for one object, proxmox_get_sdn_status for the live state on nodes.

Argument	Type	Required	Description
kind	"zone" | "vnet" | "subnet" | "controller" | "ipam" | "dns"	yes	SDN object kind: zone, vnet, subnet (needs vnet), controller (BGP/EVPN/IS-IS), ipam or dns (DNS plugin)
vnet	string		VNet the subnet belongs to (required for kind=subnet)
type	string		Only objects of this plugin type, e.g. vlan, vxlan, evpn, simple, qinq (zones); bgp, evpn, isis (controllers); pve, netbox, phpipam (ipams)
pending	boolean		Include uncommitted changes: each object shows state (new/changed/deleted) and the pending values not yet applied with proxmox_apply_sdn
running	boolean		Show the running (last applied) configuration instead of the edited one
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 500)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_sdn_object

🟢 read

Get the full configuration of one SDN zone, vnet, subnet, controller, IPAM or DNS plugin, including its digest for optimistic locking. With pending=true, uncommitted changes are shown under pending.

Argument	Type	Required	Description
kind	"zone" | "vnet" | "subnet" | "controller" | "ipam" | "dns"	yes	SDN object kind: zone, vnet, subnet (needs vnet), controller (BGP/EVPN/IS-IS), ipam or dns (DNS plugin)
id	string	yes	Object ID (zone/vnet/controller/ipam/dns name, or subnet ID such as ‘zone1-10.0.0.0-24’ or its CIDR ‘10.0.0.0/24’)
vnet	string		VNet the subnet belongs to (required for kind=subnet)
pending	boolean		Include uncommitted changes: each object shows state (new/changed/deleted) and the pending values not yet applied with proxmox_apply_sdn
running	boolean		Show the running (last applied) configuration instead of the edited one

proxmox_get_sdn_status

🟢 read

Show the live SDN state on nodes: each zone’s status (available/pending/error) per node and the status of the vnets in it. Use it after proxmox_apply_sdn to confirm the configuration came up, or to find nodes where a zone is in error.

Argument	Type	Required	Description
node	string		Only this node (default all online nodes)
zone	string		Only this zone
vnets	boolean		Include per-vnet status inside each zone (default true)

proxmox_get_sdn_pending_diff

🟢 read

Dry-run proxmox_apply_sdn for one node: shows the diff between the running and the pending network interfaces (/etc/network/interfaces.d/sdn) and FRR routing configuration. Use it to review staged SDN changes before applying them.

Argument	Type	Required	Description
node	string		Node to compute the diff for (default PROXMOX_DEFAULT_NODE or the only node)

proxmox_get_sdn_ipam_status

🟢 read

List the IP allocations recorded in an SDN IPAM (default the built-in ‘pve’ IPAM): IP, MAC, hostname, VMID, vnet/subnet and gateway entries. Use it to find which guest holds an address or which IPs are free. Related: proxmox_save_sdn_vnet_ip to add or change a mapping.

Argument	Type	Required	Description
ipam	string		IPAM ID (default ‘pve’)
vnet	string		Only entries in this vnet
vmid	integer		Only entries of this VM/container
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 1000)

proxmox_list_sdn_fabrics

🟢 read

List SDN fabrics (PVE 9 underlay networks: OpenFabric, OSPF, WireGuard, BGP) with their nodes. Give node and fabric to also read that node’s live fabric routes, neighbors and interfaces. Read-only; fabrics are edited in the web UI or with proxmox_api_request.

Argument	Type	Required	Description
pending	boolean		Include uncommitted changes: each object shows state (new/changed/deleted) and the pending values not yet applied with proxmox_apply_sdn
running	boolean		Show the running (last applied) configuration instead of the edited one
node	string		With fabric: read this node’s live routes/neighbors/interfaces for the fabric
fabric	string		Fabric ID for the live node status

proxmox_list_sdn_route_policies

🟢 read

List SDN routing policy objects (PVE 9): prefix lists with their entries, and route maps with their entries (match/set clauses). Read-only. These are referenced by controllers (route-map-in/out) and fabrics (route_filter).

Argument	Type	Required	Description
pending	boolean		Include uncommitted changes: each object shows state (new/changed/deleted) and the pending values not yet applied with proxmox_apply_sdn
running	boolean		Show the running (last applied) configuration instead of the edited one

proxmox_save_sdn_zone

🟠 write

Create (create=true) or update an SDN zone. Zone types: simple (isolated, optional SNAT/DHCP), vlan (on a VLAN-aware bridge), qinq, vxlan (overlay between peers), evpn (needs an EVPN controller). Only given fields change on update. Changes are staged as pending; run proxmox_apply_sdn to activate them on the nodes.

Argument	Type	Required	Description
zone	string	yes	Zone ID (2-8 alphanumeric characters, starting with a letter)
create	boolean		Create a new object (default false = update an existing one; only the given fields change)
type	"simple" | "vlan" | "qinq" | "vxlan" | "evpn" | "faucet"		Zone type (required when creating; can’t be changed)
bridge	string		Bridge for VLAN/QinQ zones, e.g. vmbr0
tag	integer		Service VLAN tag (QinQ outer tag)
vlan_protocol	"802.1q" | "802.1ad"		QinQ VLAN protocol
peers	string[]		VXLAN peer IPs (usually the nodes’ IPs)
controller	string		EVPN controller ID
vrf_vxlan	integer		EVPN: VNI of the zone VRF
exitnodes	string[]		EVPN: nodes acting as exit gateways
exitnodes_primary	string		EVPN: preferred exit node
advertise_subnets	boolean		EVPN: advertise subnets (type-5 routes)
mtu	integer		MTU of the vnet bridges in this zone
nodes	string[]		Restrict to these cluster nodes (default all nodes)
ipam	string		IPAM to use, e.g. ‘pve’
dhcp	"dnsmasq"		DHCP backend for automatic DHCP in simple/EVPN zones
dns	string		DNS plugin ID
reversedns	string		Reverse DNS plugin ID
dnszone	string		DNS domain zone, e.g. lab.example.com
fabric	string		PVE 9 SDN fabric used as underlay (VXLAN)
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_save_sdn_vnet

🟠 write

Create (create=true) or update an SDN vnet: a virtual network in a zone that guests attach to like a bridge (bridge=). Only given fields change on update. Changes are staged as pending; run proxmox_apply_sdn to activate them on the nodes.

Argument	Type	Required	Description
vnet	string	yes	VNet ID (up to 8 alphanumeric characters); also the bridge name guests use
create	boolean		Create a new object (default false = update an existing one; only the given fields change)
zone	string		Zone the vnet belongs to (required when creating)
tag	integer		VLAN tag (VLAN/QinQ zones) or VXLAN VNI (VXLAN/EVPN zones)
alias	string		Descriptive alias
vlanaware	boolean		Allow guests to use VLAN tags inside this vnet
isolate_ports	boolean		Isolate guest ports from each other (only uplink traffic)
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_save_sdn_subnet

🟠 write

Create (create=true) or update a subnet of an SDN vnet: gateway, SNAT and DHCP ranges (DHCP needs dhcp=dnsmasq on the zone). Only given fields change on update. Changes are staged as pending; run proxmox_apply_sdn to activate them on the nodes.

Argument	Type	Required	Description
vnet	string	yes	VNet the subnet belongs to
subnet	string	yes	Subnet in CIDR form, e.g. 10.10.0.0/24 (or its ID such as ‘zone1-10.10.0.0-24’ when updating)
create	boolean		Create a new object (default false = update an existing one; only the given fields change)
gateway	string		Gateway IP, assigned on the vnet in layer-3 zones
snat	boolean		Masquerade (SNAT) traffic leaving this subnet
dhcp_range	object[]		DHCP ranges (replaces the existing list)
dhcp_dns_server	string		DNS server handed out by DHCP
dnszoneprefix	string		DNS zone prefix, e.g. ‘adm’ -> .adm.
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_save_sdn_controller

🟠 write

Create (create=true) or update an SDN controller: evpn (the BGP-EVPN control plane for EVPN zones), bgp (per-node BGP peering/underlay), isis or faucet. Only given fields change on update. Changes are staged as pending; run proxmox_apply_sdn to activate them on the nodes.

Argument	Type	Required	Description
controller	string	yes	Controller ID
create	boolean		Create a new object (default false = update an existing one; only the given fields change)
type	"evpn" | "bgp" | "isis" | "faucet"		Controller type (required when creating)
asn	integer		Autonomous system number (evpn/bgp)
peers	string[]		Peer IP addresses (evpn/bgp)
node	string		Node this controller applies to (bgp/isis)
ebgp	boolean		Use eBGP (bgp)
ebgp_multihop	integer		eBGP multihop count (bgp)
loopback	string		Loopback interface providing the router IP (bgp)
bgp_mode	"auto" | "external" | "internal"		eBGP/iBGP selection (evpn)
fabric	string		PVE 9 SDN fabric used as underlay (evpn)
isis_domain	string		IS-IS domain name (isis)
isis_ifaces	string[]		Interfaces running IS-IS (isis)
isis_net	string		IS-IS network entity title (isis)
route_map_in	string		Route map applied to incoming routes
route_map_out	string		Route map applied to outgoing routes
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_save_sdn_ipam

🟠 write

Create (create=true) or update an IPAM plugin: pve (built-in), netbox or phpipam (external, need url and token). Only given fields change on update. Changes are staged as pending; run proxmox_apply_sdn to activate them on the nodes.

Argument	Type	Required	Description
ipam	string	yes	IPAM ID
create	boolean		Create a new object (default false = update an existing one; only the given fields change)
type	"pve" | "netbox" | "phpipam"		IPAM type (required when creating)
url	string		API URL of the external IPAM
token	string		API token of the external IPAM
section	integer		phpIPAM section ID
fingerprint	string		Expected TLS certificate SHA-256 fingerprint
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_save_sdn_dns

🟠 write

Create (create=true) or update an SDN DNS plugin (PowerDNS) used to register guest hostnames for zones with dns/dnszone set. Only given fields change on update. Changes are staged as pending; run proxmox_apply_sdn to activate them on the nodes.

Argument	Type	Required	Description
dns	string	yes	DNS plugin ID
create	boolean		Create a new object (default false = update an existing one; only the given fields change)
type	"powerdns"		Plugin type (required when creating)
url	string		PowerDNS API URL (required when creating), e.g. http://pdns:8081/api/v1/servers/localhost
key	string		PowerDNS API key (required when creating)
ttl	integer		TTL of created records
reversemaskv6	integer		IPv6 reverse zone mask
fingerprint	string		Expected TLS certificate SHA-256 fingerprint
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_sdn_object

🔴 delete · destructive

Delete an SDN zone, vnet, subnet, controller, IPAM or DNS plugin. Objects still in use (e.g. a zone with vnets, a vnet with subnets) are refused by Proxmox. Changes are staged as pending; run proxmox_apply_sdn to activate them on the nodes.

Argument	Type	Required	Description
kind	"zone" | "vnet" | "subnet" | "controller" | "ipam" | "dns"	yes	SDN object kind: zone, vnet, subnet (needs vnet), controller (BGP/EVPN/IS-IS), ipam or dns (DNS plugin)
id	string	yes	Object ID (for subnets the CIDR or subnet ID)
vnet	string		VNet the subnet belongs to (required for kind=subnet)
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit

proxmox_save_sdn_vnet_ip

🟠 write

Create (create=true) or update an IP-to-MAC mapping in a vnet’s IPAM, e.g. to reserve a fixed DHCP address for a guest. Takes effect immediately (no apply needed). See proxmox_get_sdn_ipam_status for current entries.

Argument	Type	Required	Description
vnet	string	yes	VNet ID
zone	string		Zone of the vnet (looked up from the vnet when omitted)
ip	string	yes	IP address
mac	string		MAC address to associate
vmid	integer		VM/container ID owning the IP (update only)
create	boolean		Create a new object (default false = update an existing one; only the given fields change)

proxmox_delete_sdn_vnet_ip

🔴 delete · destructive

Remove an IP mapping (IPAM entry) from a vnet, freeing the address.

Argument	Type	Required	Description
vnet	string	yes	VNet ID
zone	string		Zone of the vnet (looked up from the vnet when omitted)
ip	string	yes	IP address to remove
mac	string		MAC address of the mapping

proxmox_apply_sdn

🟠 write · destructive

Apply all pending SDN changes: writes the network and FRR configuration to every node and reloads networking. This can briefly disrupt guest networking on SDN vnets. Review with proxmox_list_sdn_objects pending=true or proxmox_get_sdn_pending_diff first, and check proxmox_get_sdn_status afterwards.

Argument	Type	Required	Description
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit
release_lock	boolean		With lock_token: release the lock after applying (default true)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_rollback_sdn

🟠 write · destructive

Roll back all pending (not yet applied) SDN changes to the running configuration (PVE 9). Irreversible: staged edits are lost. Running networking is not touched.

Argument	Type	Required	Description
lock_token	string		SDN lock token, only needed when the global SDN configuration has been locked by someone else (PVE 9); normally omit
release_lock	boolean		With lock_token: release the lock afterwards (default true)

ceph

Ceph: health, OSDs, pools, monitors, managers, metadata servers, CephFS, flags and configuration.

Tool	Access	Summary
proxmox_get_ceph_status	🟢 read	Get Ceph status
proxmox_list_ceph_osds	🟢 read	List Ceph OSDs
proxmox_get_ceph_osd	🟢 read	Get Ceph OSD details
proxmox_list_ceph_pools	🟢 read	List Ceph pools
proxmox_get_ceph_pool	🟢 read	Get Ceph pool
proxmox_list_ceph_services	🟢 read	List Ceph monitors, managers and metadata servers
proxmox_list_ceph_fs	🟢 read	List CephFS file systems
proxmox_get_ceph_flags	🟢 read	Get Ceph OSD flags
proxmox_get_ceph_crush	🟢 read	Get Ceph CRUSH map and rules
proxmox_get_ceph_config	🟢 read	Get Ceph configuration
proxmox_get_ceph_log	🟢 read	Read Ceph log
proxmox_get_ceph_metadata	🟢 read	Get Ceph daemon metadata
proxmox_check_ceph_safety	🟢 read	Check if stopping/destroying a Ceph daemon is safe
proxmox_control_ceph_osd	🟠 write	Mark OSD in/out or scrub it
proxmox_create_ceph_osd	🟠 write	Create a Ceph OSD
proxmox_delete_ceph_osd	🔴 delete	Destroy a Ceph OSD
proxmox_create_ceph_pool	🟠 write	Create a Ceph pool
proxmox_update_ceph_pool	🟠 write	Change Ceph pool settings
proxmox_delete_ceph_pool	🔴 delete	Destroy a Ceph pool
proxmox_create_ceph_service	🟠 write	Create a Ceph monitor, manager or MDS
proxmox_delete_ceph_service	🔴 delete	Destroy a Ceph monitor, manager or MDS
proxmox_create_ceph_fs	🟠 write	Create a CephFS
proxmox_delete_ceph_fs	🔴 delete	Destroy a CephFS
proxmox_set_ceph_flags	🟠 write	Set or clear Ceph OSD flags
proxmox_mute_ceph_health_check	🟠 write	Mute or unmute a Ceph health check
proxmox_control_ceph_service	🟠 write	Start, stop or restart Ceph services
proxmox_init_ceph	🟠 write	Initialise Ceph configuration

proxmox_get_ceph_status

🟢 read

Summarized Ceph cluster health: HEALTH_OK/WARN/ERR with each health check, monitor quorum, active/standby managers, OSD counts (up/in/down), PG states, raw usage and client I/O. Start here for any Ceph question; drill down with proxmox_list_ceph_osds, proxmox_list_ceph_pools or proxmox_list_ceph_services.

Argument	Type	Required	Description
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_list_ceph_osds

🟢 read

List Ceph OSDs from the OSD tree: host, up/down, in/out, device class, usage, PGs, CRUSH weight, latency and version, plus the per-host grouping and cluster-wide OSD flags (noout etc.). Filter by host, status or device class.

Argument	Type	Required	Description
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.
host	string		Only OSDs on this host
status	"up" | "down" | "in" | "out"		Only OSDs in this state
device_class	string		Only this device class, e.g. hdd, ssd, nvme
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 1000)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_ceph_osd

🟢 read

Get one OSD’s details: daemon metadata (devices, BlueStore, memory, version) and its logical volume info (block/DB/WAL devices).

Argument	Type	Required	Description
osdid	integer	yes	OSD ID number, e.g. 3 for osd.3
node	string		Node hosting the OSD (looked up from the OSD tree when omitted)

proxmox_list_ceph_pools

🟢 read

List Ceph pools with replication (size/min_size), PG count and autoscale mode (with the autoscaler’s optimal PG count), application, CRUSH rule and usage %. Related: proxmox_get_ceph_pool, proxmox_update_ceph_pool.

Argument	Type	Required	Description
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_ceph_pool

🟢 read

Get one Ceph pool’s settings (size, min_size, PGs, autoscaler, CRUSH rule, application, protection flags) and, with statistics=true, its usage and I/O statistics.

Argument	Type	Required	Description
name	string	yes	Pool name
statistics	boolean		Include usage and I/O statistics (default true)
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.

proxmox_list_ceph_services

🟢 read

List Ceph daemons of one type or all: monitors (quorum, rank), managers (active/standby) and metadata servers (MDS state, CephFS, rank), with host, address and version.

Argument	Type	Required	Description
type	"mon" | "mgr" | "mds" | "all"		Daemon type (default all)
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.

proxmox_list_ceph_fs

🟢 read

List CephFS file systems with their metadata and data pools. MDS daemons serving them are listed by proxmox_list_ceph_services.

Argument	Type	Required	Description
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.

proxmox_get_ceph_flags

🟢 read

Show which cluster-wide Ceph OSD flags are set (noout, noscrub, nodeep-scrub, norebalance, pause…). Change them with proxmox_set_ceph_flags.

No arguments.

proxmox_get_ceph_crush

🟢 read

Get the decompiled CRUSH map (devices, buckets, rules) and the list of CRUSH rule names usable as a pool’s crush_rule.

Argument	Type	Required	Description
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.
rules_only	boolean		Only list the rule names (much shorter)

proxmox_get_ceph_config

🟢 read

Read Ceph configuration: the configuration database (ceph config dump: section, name, value) and/or the ceph.conf file. Secrets such as keys are redacted.

Argument	Type	Required	Description
source	"db" | "file" | "both"		Configuration database, ceph.conf file, or both (default both)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.

proxmox_get_ceph_log

🟢 read

Read lines of the Ceph cluster log (ceph.log) from a node: health changes, OSD up/down events, slow ops and scrub errors.

Argument	Type	Required	Description
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.
limit	integer		Number of lines (default 50)
start	integer		Offset of the first line (0-based)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_ceph_metadata

🟢 read

Get metadata of every Ceph daemon (mon, mgr, mds, osd) and node: host, Ceph version and release, memory. Useful to spot daemons running an outdated version after an upgrade.

Argument	Type	Required	Description
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_check_ceph_safety

🟢 read

Ask Ceph whether stopping or destroying an OSD, monitor or MDS is safe right now (e.g. no PGs would become unavailable). Call before proxmox_delete_ceph_osd, proxmox_delete_ceph_service or stopping services.

Argument	Type	Required	Description
service	"osd" | "mon" | "mds"	yes	Daemon type
id	string	yes	Daemon ID, e.g. ‘3’ for osd.3 or the monitor name
action	"stop" | "destroy"	yes	Intended action
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.

proxmox_control_ceph_osd

🟠 write · destructive

Mark an OSD in or out of data placement, or start a (deep) scrub. Marking out starts moving its data elsewhere (rebalancing); mark in to bring it back. Set the noout flag instead for short maintenance.

Argument	Type	Required	Description
osdid	integer	yes	OSD ID number, e.g. 3 for osd.3
action	"in" | "out" | "scrub" | "deep-scrub"	yes	What to do
node	string		Node hosting the OSD (looked up when omitted)

proxmox_create_ceph_osd

🟠 write · destructive

Create a Ceph OSD on an unused disk of a node. DESTROYS ALL DATA on the disk (and on db_dev/wal_dev partitions it uses). List candidate disks with the node disk tools first.

Argument	Type	Required	Description
node	string	yes	Node to act on (where the daemon/disk is)
dev	string	yes	Block device, e.g. /dev/sdb
device_class	string		CRUSH device class, e.g. hdd, ssd, nvme (default auto-detected)
db_dev	string		Separate device for the BlueStore DB
db_dev_size	number		DB size in GiB
wal_dev	string		Separate device for the BlueStore WAL
wal_dev_size	number		WAL size in GiB
encrypted	boolean		Encrypt the OSD
osds_per_device	integer		OSDs per device (fast NVMe only; excludes db_dev/wal_dev)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_ceph_osd

🔴 delete · destructive

Destroy an OSD and remove it from the cluster. The OSD must be out and stopped first (proxmox_control_ceph_osd action=out, then proxmox_control_ceph_service action=stop service=osd.) and data rebalanced; check with proxmox_check_ceph_safety. cleanup=true also wipes the disk.

Argument	Type	Required	Description
osdid	integer	yes	OSD ID number, e.g. 3 for osd.3
node	string		Node hosting the OSD (looked up when omitted)
cleanup	boolean		Also zap the logical volumes and wipe the disk
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_create_ceph_pool

🟠 write

Create a Ceph pool, optionally erasure-coded and optionally added as Proxmox storage (add_storages). Defaults: size 3, min_size 2, application rbd.

Argument	Type	Required	Description
name	string	yes	Pool name
size	integer		Number of replicas (default 3)
min_size	integer		Minimum replicas needed to serve I/O (default 2)
pg_num	integer		Number of placement groups
pg_num_min	integer		Minimum PG count for the autoscaler
pg_autoscale_mode	"on" | "off" | "warn"		PG autoscaler mode
application	"rbd" | "cephfs" | "rgw"		Pool application (default rbd)
crush_rule	string		CRUSH rule name (see proxmox_get_ceph_crush)
target_size	string		Expected pool size for the autoscaler, e.g. 500G
target_size_ratio	number		Expected share of the cluster capacity for the autoscaler
add_storages	boolean		Also create Proxmox storage entries for the pool
erasure_coding	string		Create an erasure-coded pool, e.g. ‘k=2,m=1’ (property string; see the Proxmox docs)
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_update_ceph_pool

🟠 write · destructive

Change a pool’s size/min_size, PG count, autoscaler, application or CRUSH rule. Only given fields change. Changing size, pg_num or crush_rule moves data and can load the cluster for a long time.

Argument	Type	Required	Description
name	string	yes	Pool name
size	integer		Number of replicas (default 3)
min_size	integer		Minimum replicas needed to serve I/O (default 2)
pg_num	integer		Number of placement groups
pg_num_min	integer		Minimum PG count for the autoscaler
pg_autoscale_mode	"on" | "off" | "warn"		PG autoscaler mode
application	"rbd" | "cephfs" | "rgw"		Pool application (default rbd)
crush_rule	string		CRUSH rule name (see proxmox_get_ceph_crush)
target_size	string		Expected pool size for the autoscaler, e.g. 500G
target_size_ratio	number		Expected share of the cluster capacity for the autoscaler
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_ceph_pool

🔴 delete · destructive

Destroy a Ceph pool and ALL data in it. Refused while in use unless force=true. Optionally removes the Proxmox storage entries for it.

Argument	Type	Required	Description
name	string	yes	Pool name
force	boolean		Destroy even if guest disks still use it
remove_storages	boolean		Also remove Proxmox storage entries for this pool
remove_ecprofile	boolean		Remove the erasure-code profile (default true where applicable)
node	string		Node to query through (any node with Ceph installed; default PROXMOX_DEFAULT_NODE or the first online node). Results are cluster-wide.
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_create_ceph_service

🟠 write

Create a Ceph monitor (mon), manager (mgr) or metadata server (mds) on a node. The daemon ID defaults to the node name. The first monitor also gets a manager.

Argument	Type	Required	Description
type	"mon" | "mgr" | "mds"	yes	Daemon type
node	string	yes	Node to act on (where the daemon/disk is)
id	string		Daemon ID (default the node name)
mon_address	string[]		mon only: IP address(es) in the Ceph public network (default auto-detected)
hotstandby	boolean		mds only: poll the active MDS’s log for faster failover
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_delete_ceph_service

🔴 delete · destructive

Destroy a Ceph monitor, manager or metadata server. The last monitor can’t be removed; keep enough monitors for quorum. Check with proxmox_check_ceph_safety first.

Argument	Type	Required	Description
type	"mon" | "mgr" | "mds"	yes	Daemon type
node	string	yes	Node to act on (where the daemon/disk is)
id	string	yes	Daemon ID (see proxmox_list_ceph_services)
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_create_ceph_fs

🟠 write

Create a CephFS file system (with its data and metadata pools). Needs at least one MDS (proxmox_create_ceph_service type=mds). add_storage=true also adds it as Proxmox storage.

Argument	Type	Required	Description
name	string		File system name (default cephfs)
node	string	yes	Node to act on (where the daemon/disk is)
pg_num	integer		PGs of the data pool (default 128; metadata pool gets a quarter)
add_storage	boolean		Add it as Proxmox storage
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_delete_ceph_fs

🔴 delete · destructive

Destroy a CephFS file system. Refused while an enabled Proxmox cephfs storage uses it. remove_pools=true also deletes its pools and ALL data.

Argument	Type	Required	Description
name	string	yes	File system name
node	string	yes	Node to act on (where the daemon/disk is)
remove_pools	boolean		Also remove the data and metadata pools
remove_storages	boolean		Also remove the Proxmox storage entries for it
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_set_ceph_flags

🟠 write · destructive

Set (true) or clear (false) cluster-wide Ceph OSD flags; omitted flags are left alone (nodeep-scrub is nodeep_scrub here). Typical: noout=true before node maintenance, then noout=false afterwards. pause=true stops ALL client I/O.

Argument	Type	Required	Description
nobackfill	boolean		true sets, false clears: suspend PG backfilling
nodeep_scrub	boolean		true sets, false clears: disable deep scrubbing
nodown	boolean		true sets, false clears: ignore OSD failure reports (OSDs won’t be marked down)
noin	boolean		true sets, false clears: don’t mark restarted OSDs back in
noout	boolean		true sets, false clears: don’t mark down OSDs out (use during maintenance)
norebalance	boolean		true sets, false clears: suspend PG rebalancing
norecover	boolean		true sets, false clears: suspend PG recovery
noscrub	boolean		true sets, false clears: disable scrubbing
notieragent	boolean		true sets, false clears: suspend cache tiering
noup	boolean		true sets, false clears: don’t allow OSDs to start
pause	boolean		true sets, false clears: pause ALL client reads and writes
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_mute_ceph_health_check

🟠 write

Mute (or unmute) a Ceph health check such as AUTH_INSECURE_CLIENT_KEY_TYPE so it no longer degrades the health status; it stays visible in proxmox_get_ceph_status. Optionally for a limited time (ttl).

Argument	Type	Required	Description
code	string	yes	Health check code from proxmox_get_ceph_status, e.g. OSD_NEARFULL
mute	boolean		true to mute (default), false to unmute
ttl	string		Mute duration, e.g. ‘2h’, ‘3d’, ‘1w’ (default no expiry)
sticky	boolean		Keep the mute even if the check gets worse

proxmox_control_ceph_service

🟠 write · destructive

Start, stop or restart Ceph services on a node: all of them (default ceph.target), all of one type (‘osd’, ‘mon’, ‘mgr’, ‘mds’) or one daemon as ., e.g. ‘osd.3’, ‘mon.pve1’, ‘mgr.pve1’, ‘mds.pve1’. Stopping can make data unavailable; check proxmox_check_ceph_safety and consider the noout flag.

Argument	Type	Required	Description
action	"start" | "stop" | "restart"	yes	What to do
node	string	yes	Node to act on (where the daemon/disk is)
service	string		Service as [.], e.g. osd.3, mon.pve1 or osd (all OSDs); default ceph.target = all Ceph services on the node
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_init_ceph

🟠 write

Create the initial Ceph configuration (ceph.conf) for the cluster with the public and optional cluster network. Run once on the first node after installing Ceph, then create monitors. Existing settings are preserved on re-run.

Argument	Type	Required	Description
node	string	yes	Node to act on (where the daemon/disk is)
network	string		Public network for Ceph traffic in CIDR, e.g. 10.10.10.0/24
cluster_network	string		Separate network for OSD replication/heartbeat traffic (CIDR)
size	integer		Default pool replicas (default 3)
min_size	integer		Default pool min_size (default 2)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

pools

Resource pools and their members.

Tool	Access	Summary
proxmox_list_pools	🟢 read	List resource pools
proxmox_get_pool	🟢 read	Get resource pool
proxmox_create_pool	🟠 write	Create resource pool
proxmox_update_pool	🟠 write	Update resource pool
proxmox_delete_pool	🔴 delete	Delete resource pool

proxmox_list_pools

🟢 read

List resource pools (groups of VMs, containers and storage used for permissions and organisation) with their comments and member counts. Not ZFS or Ceph pools; see proxmox_get_pool for members.

Argument	Type	Required	Description
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_pool

🟢 read

Get a resource pool’s comment and members: guests (status, node, CPU/memory use) and storage (usage).

Argument	Type	Required	Description
poolid	string	yes	Pool ID, e.g. “production” (nested pools as “parent/child”; see proxmox_list_pools)
type	"qemu" | "lxc" | "storage"		Only members of this type
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_create_pool

🟠 write

Create a resource pool. Add VMs, containers and storage to it with proxmox_update_pool.

Argument	Type	Required	Description
poolid	string	yes	Pool ID, e.g. “production” (nested pools as “parent/child”; see proxmox_list_pools)
comment	string		Description

proxmox_update_pool

🟠 write

Change a resource pool’s comment and add or remove member guests and storage. A guest can only be in one pool; set allow_move to move it here from another pool.

Argument	Type	Required	Description
poolid	string	yes	Pool ID, e.g. “production” (nested pools as “parent/child”; see proxmox_list_pools)
comment	string		New description
add_vms	integer[]		Guest VMIDs to add
remove_vms	integer[]		Guest VMIDs to remove
add_storage	string[]		Storage IDs to add
remove_storage	string[]		Storage IDs to remove
allow_move	boolean		Move added guests out of their current pool instead of failing

proxmox_delete_pool

🔴 delete · destructive

Delete a resource pool. It must be empty: remove its members with proxmox_update_pool first. The guests and storage themselves are not affected.

Argument	Type	Required	Description
poolid	string	yes	Pool ID, e.g. “production” (nested pools as “parent/child”; see proxmox_list_pools)

replication

Storage replication jobs, their status and logs.

Tool	Access	Summary
proxmox_list_replication_jobs	🟢 read	List replication jobs
proxmox_get_replication_job	🟢 read	Get replication job
proxmox_save_replication_job	🟠 write	Create or update replication job
proxmox_delete_replication_job	🔴 delete	Delete replication job
proxmox_run_replication_now	🟠 write	Run replication now
proxmox_get_replication_log	🟢 read	Get replication log

proxmox_list_replication_jobs

🟢 read

List storage replication jobs (ZFS-based guest replication to another node) with guest, target, schedule, rate limit and live status from the source node: last/next sync, duration, failure count and last error.

Argument	Type	Required	Description
guest	integer		Only jobs for this guest VMID
target	string		Only jobs replicating to this node
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_replication_job

🟢 read

Get one replication job’s configuration (with digest for safe updates) and its current status on the source node.

Argument	Type	Required	Description
id	string	yes	Replication job ID: -, e.g. “100-0” (see proxmox_list_replication_jobs)
node	string		Node the guest currently runs on (the replication source). Looked up from the guest when omitted.

proxmox_save_replication_job

🟠 write

Create a replication job for a guest (pass guest and target; the job number is picked automatically) or update an existing one (pass id). Replication needs the guest’s disks on ZFS storage that exists on both nodes. Schedules use systemd calendar syntax, e.g. “/15” (every 15 min, default), “/5”, “hourly”, “22:30”.

Argument	Type	Required	Description
id	string		Job ID to update, or to create with a specific job number, e.g. “100-0”
guest	integer		Guest VMID (to create a job without picking the job number)
target	string		Target node (required when creating; can’t be changed afterwards)
schedule	string		Schedule in systemd calendar-event format (default “*/15”)
rate	number		Bandwidth limit in MB/s
comment	string		Description
disable	boolean		Disable (true) or enable (false) the job
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_replication_job

🔴 delete · destructive

Mark a replication job for removal. The job then removes its replication snapshots (and, unless keep is set, the replicated volumes on the target) and deletes itself on its next run. force removes only the config entry without cleanup.

Argument	Type	Required	Description
id	string	yes	Replication job ID: -, e.g. “100-0” (see proxmox_list_replication_jobs)
keep	boolean		Keep the replicated data on the target node
force	boolean		Remove the job config immediately without any cleanup

proxmox_run_replication_now

🟠 write

Schedule a replication job to run as soon as possible instead of waiting for its schedule. Check the result with proxmox_get_replication_job or proxmox_get_replication_log.

Argument	Type	Required	Description
id	string	yes	Replication job ID: -, e.g. “100-0” (see proxmox_list_replication_jobs)
node	string		Node the guest currently runs on (the replication source). Looked up from the guest when omitted.
wait	boolean		Wait for the Proxmox task to finish and return its result and log (default true, up to PROXMOX_TASK_TIMEOUT_MS). With false the task ID (UPID) is returned immediately; follow it with proxmox_get_task.

proxmox_get_replication_log

🟢 read

Read the log of a replication job’s last run from the source node, e.g. to diagnose a failing job.

Argument	Type	Required	Description
id	string	yes	Replication job ID: -, e.g. “100-0” (see proxmox_list_replication_jobs)
node	string		Node the guest currently runs on (the replication source). Looked up from the guest when omitted.
start	integer		First line to return (default 0)
limit	integer		Maximum lines (default 500)

notifications

Notification targets (sendmail, SMTP, Gotify, webhooks) and matchers.

Tool	Access	Summary
proxmox_list_notification_targets	🟢 read	List notification targets
proxmox_get_notification_endpoint	🟢 read	Get notification endpoint
proxmox_save_notification_endpoint	🟠 write	Create or update a notification endpoint
proxmox_delete_notification_endpoint	🔴 delete	Delete a notification endpoint
proxmox_test_notification_target	🟠 write	Send a test notification
proxmox_list_notification_matchers	🟢 read	List notification matchers
proxmox_get_notification_matcher	🟢 read	Get notification matcher
proxmox_save_notification_matcher	🟠 write	Create or update a notification matcher
proxmox_delete_notification_matcher	🔴 delete	Delete a notification matcher
proxmox_get_notification_matcher_fields	🟢 read	Get notification matcher fields

proxmox_list_notification_targets

🟢 read

List all notification targets (endpoints of every type: sendmail, smtp, gotify, webhook) with type, disabled state, origin and comment. details=true adds each endpoint’s configuration (secrets redacted). Matchers decide which notifications go to which target; see proxmox_list_notification_matchers.

Argument	Type	Required	Description
details	boolean		Include each endpoint’s full configuration (one extra call per type)

proxmox_get_notification_endpoint

🟢 read

Get one notification endpoint’s configuration. The type is looked up when omitted. Tokens, passwords and webhook secrets are redacted; webhook headers and body are shown decoded (credential-like headers redacted).

Argument	Type	Required	Description
name	string	yes	Endpoint/target name (see proxmox_list_notification_targets)
type	"sendmail" | "smtp" | "gotify" | "webhook"		Endpoint type: sendmail (local mail), smtp, gotify or webhook
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_save_notification_endpoint

🟠 write

Create (create=true) or update a notification endpoint of any type. Only the given fields change on update. sendmail: mailto and/or mailto_user, from_address, author. smtp: server, from_address (required), port, mode, username, password, mailto/mailto_user, author. gotify: server URL and token (required). webhook: url and method (required), headers, body (plain text; Proxmox templates like {{ title }} / {{ message }} work), secrets (referenced as {{ secrets. }}). Header, body and secret values are base64-encoded for you. Afterwards route notifications to it with proxmox_save_notification_matcher and try it with proxmox_test_notification_target.

Argument	Type	Required	Description
type	"sendmail" | "smtp" | "gotify" | "webhook"	yes	Endpoint type: sendmail (local mail), smtp, gotify or webhook
name	string	yes	Endpoint/target name (see proxmox_list_notification_targets)
create	boolean		Create a new endpoint (default false = update)
comment	string		Comment
disable	boolean		Disable the endpoint
mailto	string[]		sendmail/smtp: recipient email addresses
mailto_user	string[]		sendmail/smtp: users whose configured email is used, e.g. [“root@pam”]
from_address	string		sendmail/smtp: From address (required for smtp)
author	string		sendmail/smtp: author name (default ‘Proxmox VE’)
server	string		smtp: server host name; gotify: server URL
port	integer		smtp: port (default 465 tls, 587 starttls, 25 insecure)
mode	"insecure" | "starttls" | "tls"		smtp: encryption (default tls)
username	string		smtp: login user name
password	string		smtp: login password (never echoed)
token	string		gotify: application token (never echoed)
url	string		webhook: URL (may use {{ secrets. }})
method	"post" | "put" | "get"		webhook: HTTP method
headers	object		webhook: HTTP headers as {name: value} (replaces all headers)
body	string		webhook: request body template in plain text
secrets	object		webhook: secrets as {name: value} (replaces all secrets; never echoed)
delete	string[]		Settings to remove/reset, e.g. [“comment”, “mailto-user”] (Proxmox names)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_notification_endpoint

🔴 delete · destructive

Delete a notification endpoint (the type is looked up when omitted). Remove it from matchers first, or they will reference a missing target.

Argument	Type	Required	Description
name	string	yes	Endpoint/target name (see proxmox_list_notification_targets)
type	"sendmail" | "smtp" | "gotify" | "webhook"		Endpoint type: sendmail (local mail), smtp, gotify or webhook

proxmox_test_notification_target

🟠 write

Send a test notification to a target to check it is configured correctly (mail delivered, webhook reachable…). Errors from the endpoint are returned.

Argument	Type	Required	Description
name	string	yes	Endpoint/target name (see proxmox_list_notification_targets)

proxmox_list_notification_matchers

🟢 read

List notification matchers: rules that route notifications (by severity, metadata fields such as type/hostname/job-id, and calendar time) to targets.

No arguments.

proxmox_get_notification_matcher

🟢 read

Get one notification matcher’s rules and targets (plus its digest for safe updates).

Argument	Type	Required	Description
name	string	yes	Matcher name (see proxmox_list_notification_matchers)

proxmox_save_notification_matcher

🟠 write

Create (create=true) or update a notification matcher. Given lists replace the existing ones. A matcher with no match rules matches everything. match_severity: info, notice, warning, error, unknown. match_field: ‘(exact|regex):=’, e.g. ‘exact:type=vzdump’ or ‘regex:hostname=^pve’; see proxmox_get_notification_matcher_fields for known fields and values. match_calendar: time windows like ‘mon..fri 8-17’. mode: all (default) or any of the rules must match.

Argument	Type	Required	Description
name	string	yes	Matcher name (see proxmox_list_notification_matchers)
create	boolean		Create a new matcher (default false = update)
targets	string[]		Target names to notify on match
match_severity	("info" | "notice" | "warning" | "error" | "unknown")[]		Severities to match
match_field	string[]		Metadata rules, e.g. [“exact:type=vzdump”, “regex:hostname=^pve1$”]
match_calendar	string[]		Calendar windows, e.g. [“mon..fri 9-17”]
mode	"all" | "any"		Whether all (default) or any of the rules must match
invert_match	boolean		Invert the whole matcher
disable	boolean		Disable the matcher
comment	string		Comment
delete	string[]		Settings to remove/reset, e.g. [“comment”, “mailto-user”] (Proxmox names)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_notification_matcher

🔴 delete · destructive

Delete a notification matcher. Notifications it routed will no longer reach its targets.

Argument	Type	Required	Description
name	string	yes	Matcher name (see proxmox_list_notification_matchers)

proxmox_get_notification_matcher_fields

🟢 read

List the metadata fields notifications carry (type, hostname, job-id…) and their known values, for writing match_field rules in proxmox_save_notification_matcher.

No arguments.

hardware

PCI and USB devices, mediated devices, resource mappings, CPU models and QEMU capabilities.

Tool	Access	Summary
proxmox_list_node_pci_devices	🟢 read	List PCI devices
proxmox_list_node_mdev_types	🟢 read	List mediated device types
proxmox_list_node_usb_devices	🟢 read	List USB devices
proxmox_get_node_capabilities	🟢 read	Get node QEMU capabilities
proxmox_list_resource_mappings	🟢 read	List resource mappings
proxmox_get_resource_mapping	🟢 read	Get a resource mapping
proxmox_save_resource_mapping	🟠 write	Create or update a resource mapping
proxmox_delete_resource_mapping	🔴 delete	Delete a resource mapping
proxmox_list_custom_cpu_models	🟢 read	List custom CPU models
proxmox_get_custom_cpu_model	🟢 read	Get a custom CPU model
proxmox_save_custom_cpu_model	🟠 write	Create or update a custom CPU model
proxmox_delete_custom_cpu_model	🔴 delete	Delete a custom CPU model

proxmox_list_node_pci_devices

🟢 read

List a node’s PCI devices for passthrough planning: address, class, vendor/device names and IDs, IOMMU group (with the other devices in the same group, which must be passed through together) and whether it supports mediated devices (vGPU). Memory controllers, bridges and processors are hidden unless all=true. IOMMU group -1 means IOMMU is off.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
class	"storage" | "network" | "display" | "multimedia" | "bridge" | "serial-bus" | "wireless" | "accelerator" | string		Only this class: a name (display, network, storage, multimedia, serial-bus, accelerator…) or hex class code prefix, e.g. 03 or 0300
mdev_only	boolean		Only devices that support mediated devices (vGPU)
all	boolean		Include memory controllers, bridges and processors (hidden by default)
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields
limit	integer		Maximum number of results (default 500)
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_list_node_mdev_types

🟢 read

List the mediated device (mdev, e.g. NVIDIA vGPU / Intel GVT-g) types a PCI device offers, with how many instances are still available. Use a device with mdev support from proxmox_list_node_pci_devices.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
pci_id	string	yes	PCI address (e.g. 0000:01:00.0) or the ID of a PCI resource mapping

proxmox_list_node_usb_devices

🟢 read

List a node’s USB devices for passthrough: vendor:product ID, manufacturer and product names, bus/port path, speed and serial. Pass a device to a VM by ID (host=vendor:product) or port (host=bus-port), or via a USB resource mapping.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_node_capabilities

🟢 read

Get what a node’s QEMU supports for VM configuration: CPU models (built-in and custom), machine types/versions (q35, i440fx) and the VM-specific CPU flags that can be toggled. Use it to pick valid values for a VM’s cpu/machine options.

Argument	Type	Required	Description
node	string		Node name. Defaults to PROXMOX_DEFAULT_NODE, or the only node on a single-node install. See proxmox_list_nodes.
sections	("cpu_models" | "machines" | "cpu_flags")[]		Which parts to return (default all)
arch	"x86_64" | "aarch64"		Guest architecture (default the host’s)

proxmox_list_resource_mappings

🟢 read

List cluster resource mappings of one kind: PCI or USB devices, or directories (for virtiofs), each mapping a logical name to the device/path on every node. VMs reference them as e.g. hostpci0: mapping=, which allows migration. With check_node, Proxmox validates the entries for that node.

Argument	Type	Required	Description
kind	"pci" | "usb" | "dir"	yes	Mapping kind: pci (passthrough devices), usb, or dir (virtiofs directories)
check_node	string		Validate the mappings against this node’s hardware and report problems
search	string		Case-insensitive substring filter on names, IDs, tags and similar fields

proxmox_get_resource_mapping

🟢 read

Get one PCI, USB or directory resource mapping with its per-node entries and digest.

Argument	Type	Required	Description
kind	"pci" | "usb" | "dir"	yes	Mapping kind: pci (passthrough devices), usb, or dir (virtiofs directories)
id	string	yes	Mapping ID

proxmox_save_resource_mapping

🟠 write

Create (create=true) or update a cluster resource mapping for PCI or USB passthrough or a virtiofs directory. map lists one entry per node (it replaces the whole list when given). Get device paths and IDs from proxmox_list_node_pci_devices / proxmox_list_node_usb_devices.

Argument	Type	Required	Description
kind	"pci" | "usb" | "dir"	yes	Mapping kind: pci (passthrough devices), usb, or dir (virtiofs directories)
id	string	yes	Mapping ID (a name such as ‘gpu0’)
create	boolean		Create a new mapping (default false = update an existing one)
map	(string | object)[]		Per-node entries (required when creating)
description	string		Description of the mapping
mdev	boolean		pci only: devices provide mediated devices (vGPU)
live_migration_capable	boolean		pci only: devices support live migration (experimental)
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_resource_mapping

🔴 delete · destructive

Delete a PCI, USB or directory resource mapping. VMs still referencing it will fail to start.

Argument	Type	Required	Description
kind	"pci" | "usb" | "dir"	yes	Mapping kind: pci (passthrough devices), usb, or dir (virtiofs directories)
id	string	yes	Mapping ID

proxmox_list_custom_cpu_models

🟢 read

List cluster-wide custom CPU models (base model plus flag changes). VMs use them as cpu: custom-. Related: proxmox_get_node_capabilities for built-in models and flags.

Argument	Type	Required	Description
raw	boolean		Return the full unprocessed objects from the API (larger)

proxmox_get_custom_cpu_model

🟢 read

Get one custom CPU model definition, including its digest.

Argument	Type	Required	Description
name	string	yes	Model name, with or without the ‘custom-’ prefix

proxmox_save_custom_cpu_model

🟠 write

Create (create=true) or update a custom CPU model, e.g. a migration-safe baseline with selected flags. Only given fields change on update. Running VMs pick up changes on their next start.

Argument	Type	Required	Description
name	string	yes	Model name (the ‘custom-’ prefix is optional)
create	boolean		Create a new model (default false = update an existing one)
reported_model	string		Base QEMU CPU model reported to the guest, e.g. host, kvm64, x86-64-v2-AES, EPYC-Rome, Skylake-Server (required when creating)
flags	string[]		CPU flags to add (+flag) or remove (-flag), e.g. [“+aes”, “-pcid”]
hidden	boolean		Hide that the guest runs under KVM
hv_vendor_id	string		Hyper-V vendor ID reported to Windows guests
phys_bits	string		Physical address bits reported to the guest (8-64 or ‘host’)
guest_phys_bits	integer		Physical address bits usable by the guest
level	integer		Maximum basic CPUID leaf
delete	string[]		Config keys to remove/reset to default, e.g. [“net1”, “description”] (sent as the API’s delete parameter)
digest	string		Only apply the change if the current config digest matches (optimistic locking; from the matching get tool)
extra	object		Additional raw Proxmox API parameters (advanced; names as in the Proxmox API viewer). Merged last, so they override typed arguments.

proxmox_delete_custom_cpu_model

🔴 delete · destructive

Delete a custom CPU model. VMs still using it (cpu: custom-) will fail to start.

Argument	Type	Required	Description
name	string	yes	Model name, with or without the ‘custom-’ prefix

raw

A raw API escape hatch for anything the other tools don’t cover. It is limited to GET requests unless writes are enabled.

Tool	Access	Summary
proxmox_api_request	🟢 read	Raw Proxmox API request

proxmox_api_request

🟢 read · destructive

Call any Proxmox VE API endpoint directly, for anything the other tools don’t cover. path is relative to /api2/json, e.g. /nodes/pve1/qemu/100/firewall/options. Parameters go in the query string for GET/DELETE and in the form body for POST/PUT. All HTTP methods are allowed.

Argument	Type	Required	Description
method	"GET" | "POST" | "PUT" | "DELETE"		HTTP method (default GET)
path	string	yes	Path relative to /api2/json, starting with /
params	object		API parameters (booleans are sent as 1/0, arrays as repeated keys)
redact	boolean		Redact password/secret/key fields in the response (default true)

Prompts

Prompts are ready-made requests that tell the model which tools to call and what to report. In Claude Code they appear as slash commands, such as /mcp__proxmox__cluster_health_check.

cluster_health_check

Overall health review of the Proxmox cluster: quorum, nodes, guests, storage, Ceph, HA, backups and recent failed tasks.

troubleshoot_guest

Investigate why a VM or container is down, slow or unreachable.

Argument	Required	Description
guest	yes	VMID or name of the VM/container
symptom		What’s wrong, e.g. ‘won’t start’, ‘slow’, ‘no network’

capacity_planning

Analyse CPU, memory and storage headroom across nodes and suggest rebalancing or upgrades.

Argument	Required	Description
timeframe		Period to analyse (default week)

backup_audit

Check that every guest is backed up, backups are recent and succeeding, and retention is sensible.

security_review

Review users, tokens, permissions, firewall, certificates and updates for security issues.

update_review

List pending package updates on every node and propose a safe rolling upgrade order.

snapshot_cleanup

Find old or forgotten snapshots across all guests and propose which to delete.

Argument	Required	Description
older_than_days		Consider snapshots older than this many days (default 14)

deploy_vm

Plan and create a new VM, from a template (cloud-init) or an ISO, choosing node, storage and network sensibly.

Argument	Required	Description
name	yes	Name for the new VM
spec		What it’s for and how big, e.g. ‘Debian 12 web server, 2 cores, 4 GB, 32 GB disk, VLAN 20’