@false00/pi-proxmox

Production-focused Proxmox VE automation for the Pi coding agent.

@false00/pi-proxmox exposes 142 Pi tools for managing Proxmox clusters: VMs, LXC containers, storage, cluster state, firewall rules, backups, HA, replication, access control, task tracking, and universal raw API access through the Proxmox REST API.

| Resource | Link | |---|---| | npm | @false00/pi-proxmox | | GitHub | github.com/false00/pi-proxmox | | License | MIT | | Changelog | CHANGELOG.md | | Security policy | SECURITY.md | | Compatibility notes | docs/COMPATIBILITY.md | | Examples | docs/EXAMPLES.md | | Permissions guide | docs/PERMISSIONS.md | | Troubleshooting | docs/TROUBLESHOOTING.md | | Contributing guide | CONTRIBUTING.md |

Why this package

This package is designed for people who want Pi to operate real Proxmox infrastructure without hand-writing API calls.

What makes it useful:

• Broad coverage — 142 tools spanning VM, LXC, storage, cluster, firewall, backup, HA, replication, task workflows, and universal raw API access
• Consistent wrapper strategy — dedicated tools for common workflows, universal raw tools for edge cases, with parameters that intentionally stay close to the Proxmox API where practical
• Agent-friendly responses — structured JSON output for read/list/status tools, plus progress streaming for long-running operations
• Operational safety — destructive actions are explicit, task-based operations return UPIDs, and tool failures surface as real Pi tool errors
• Live-tested behavior — the repo includes integration tests against a real Proxmox host, including VM/LXC lifecycle tests, package checks, raw API coverage tests, and runtime-behavior tests
• Pi-native packaging — installable as a Pi package through npm and loadable directly via pi install or pi -e

What you get

Tool coverage by area:

| Area | Tool count | |---|---:| | Virtual machines | 23 | | VM guest agent | 13 | | LXC containers | 21 | | Nodes | 18 | | Storage + pools | 11 | | Cluster | 9 | | Backup | 3 | | Firewall | 11 | | Access control | 16 | | High availability | 7 | | Replication | 5 | | Tasks | 3 | | Universal raw API coverage | 2 | | Total | 142 |

Official API coverage audit

Against the official Proxmox VE API viewer at https://pve.proxmox.com/pve-docs/api-viewer/, the API surface audited on 2026-06-17 exposed:

• 444 routes
• 675 route/method combinations
• top-level namespaces: access, cluster, nodes, pools, storage, and version
• standard REST methods: GET, POST, PUT, and DELETE

This package covers the common day-to-day workflows with dedicated proxmox_* tools and covers the rest of the official API surface with two universal escape hatches:

• proxmox_api_call — generic GET/POST/PUT/DELETE access to any Proxmox API path under /api2/json
• proxmox_api_upload_file — generic multipart upload access for upload-style endpoints

Design philosophy

This package is intentionally a thin-but-usable Proxmox wrapper for Pi.

That means:

• dedicated tools are added for common operational workflows
• raw universal tools exist so official API reach does not depend on hundreds of niche one-off wrappers
• parameter names and many flag conventions stay close to upstream Proxmox behavior when practical
• the package prefers predictable behavior and maintainability over hiding every Proxmox detail behind a custom abstraction layer

Stability guarantees

This repository aims to provide a stable automation surface for Pi users.

Current guarantees:

• published tool names are treated as stable once released
• destructive operations are explicit in tool naming and documentation
• dedicated tools stay close to upstream Proxmox semantics where practical
• universal raw tools are the compatibility layer for long-tail official endpoints
• proxmox_node_execute prefers official args command objects and still accepts legacy body as a compatibility alias

Install

Install into Pi as a package:

pi install npm:@false00/pi-proxmox

Use it for a single run without changing your settings:

pi -e npm:@false00/pi-proxmox

For local development from this repository:

pi -e .

VS Code Copilot through MCP

This repository also includes a stdio MCP bridge that exposes the same 142 proxmox_* tools to VS Code Copilot and other MCP clients. It reuses the existing Pi extension entrypoint and the same local configuration at ~/.config/pi-proxmox/.env; do not put tokens or passwords in mcp.json.

For a local checkout, configure the MCP client with an absolute path to the bridge:

{
  "servers": {
    "pi-proxmox": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/pi-proxmox/dist/mcp-server.js"]
    }
  }
}

Then start or trust the MCP server in the client. The bridge preserves the existing tool names, TypeBox-derived JSON schemas, Proxmox REST client, ticket-auth fallback for proxmox_node_execute, and structured error behavior.

Quick start

After installing, ask Pi to operate your Proxmox cluster in plain English:

List all VMs on pve1
Create a Debian container with 2GB RAM on pve1
Show cluster status
Resize disk scsi0 on VM 101 by +20G
Check recent tasks on pve1

Pi will call tools like proxmox_vm_list, proxmox_lxc_create, proxmox_cluster_status, and proxmox_task_list behind the scenes.

Top tasks and example prompts

Common things users ask Pi to do with this package:

List all VMs on pve1
Show running containers on pve1
Create a Debian LXC with 2 GB RAM on pve1
Clone VM 900 to a new VM 101 named web-01
Take a snapshot of VM 101 named pre-update
Roll back VM 101 to snapshot pre-update
Upload an ISO to local storage on pve1
Show failed tasks on pve1
Check cluster quorum and node health
Run hostname inside VM 118 through the guest agent

Choosing dedicated tools vs raw tools

Use the package in this order:

1. Dedicated proxmox_* tools first for common workflows like VM lifecycle, LXC lifecycle, storage, firewall, HA, replication, and backups
2. Use proxmox_api_call when the official API supports something that does not yet have a dedicated tool
3. Use proxmox_api_upload_file for multipart upload endpoints such as storage uploads

This keeps everyday usage ergonomic while still preserving full official API reach.

Operational docs

For day-to-day use and troubleshooting, see:

• docs/EXAMPLES.md
• docs/PERMISSIONS.md
• docs/TROUBLESHOOTING.md

Trust, safety, and operating model

This is a full-access infrastructure package. Like any Pi extension, it can perform real changes in your environment if Pi is allowed to call its tools.

Important expectations:

• The package does not shell into LXC containers; Proxmox does not expose a comparable API for that
• VM in-guest command execution is only available through the QEMU Guest Agent tools
• Destructive operations such as delete, stop, reboot, rollback, firewall changes, and ACL updates are exposed as explicit tools
• Long-running operations return Proxmox task identifiers or agent PIDs so Pi can continue tracking them
• Runtime failures are thrown back to Pi as proper tool errors, not fake success payloads
• In the verified test environment, /nodes/{node}/execute required password/ticket fallback even though normal token-based API calls succeeded
• /nodes/{node}/execute is a real Proxmox endpoint for batching node-relative API requests; it does not provide arbitrary shell execution on the host

If you are evaluating the package for production use, review:

• SECURITY.md
• AGENTS.md
• CHANGELOG.md
• docs/COMPATIBILITY.md
• tests/ for behavioral coverage
• docs/ for the bundled Proxmox API reference material used by the project

Configuration

Requirements

• Node.js 22+
• A Pi runtime with extension support
• A reachable Proxmox VE cluster over HTTPS

Connection settings

Create ~/.config/pi-proxmox/.env:

# --- Connection ---
PROXMOX_HOST=192.168.1.100
PROXMOX_PORT=8006
PROXMOX_VERIFY_SSL=false

# --- API Token (recommended) ---
PROXMOX_TOKEN_ID=root@pam!automation
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# --- Password fallback (optional; mainly used when /execute rejects API-token auth) ---
PROXMOX_USERNAME=root@pam
PROXMOX_PASSWORD=yourpassword

# --- Timeouts ---
PROXMOX_TIMEOUT_MS=30000
PROXMOX_TOOL_TIMEOUT_MS=30000

Values in ~/.config/pi-proxmox/.env take precedence over environment variables.

Recommended token setup

Create an admin token with privilege separation disabled if you want the full toolset to work.

Web UI: Go to Datacenter → Permissions → API Tokens, click Add, select your user (for example root@pam), enter a token name (for example automation), and uncheck Privilege Separation.

CLI:

pveum user token add root@pam automation --privsep=0

Without --privsep=0 or with privilege separation left enabled in the UI, the token can appear to work while silently returning empty results for resources like VMs, containers, or storage.

Token format

PROXMOX_TOKEN_ID uses the format:

USER@REALM!TOKENNAME

Examples:

• root@pam!automation
• john@pve!ops-bot

Store the .env file with restricted permissions when possible:

chmod 600 ~/.config/pi-proxmox/.env

Environment variables

| Variable | Purpose | |---|---| | PROXMOX_HOST | Proxmox server hostname or IP | | PROXMOX_PORT | HTTPS port, default 8006 | | PROXMOX_TOKEN_ID | Token ID such as root@pam!automation | | PROXMOX_TOKEN_SECRET | Token secret UUID | | PROXMOX_USERNAME | Username for password-based auth fallback | | PROXMOX_PASSWORD | Password for password-based auth fallback, mainly for /nodes/{node}/execute | | PROXMOX_VERIFY_SSL | Verify TLS certificates, true or false | | PROXMOX_TIMEOUT_MS | Per-request API timeout in milliseconds | | PROXMOX_TOOL_TIMEOUT_MS | Total Pi tool execution timeout in milliseconds |

Configuration priority

1. ~/.config/pi-proxmox/.env
2. Constructor options when embedding the client directly
3. Environment variables
4. Built-in defaults

Runtime behavior

Output model

• List, status, config, and inspection tools return JSON text for Pi to consume
• Long-running tools can stream progress updates into Pi via onUpdate(...)
• Many asynchronous Proxmox operations return a task UPID
• Guest-agent execution returns a PID that can be checked with proxmox_vm_agent_exec_status

Error model

Tool failures are thrown back to Pi as proper tool errors. The error message body is JSON with fields such as:

• error
• category
• guidance
• retryable
• endpoint
• method
• httpStatus

Standard error categories:

| Category | Meaning | |---|---| | validation | Invalid tool parameters | | authentication | Bad credentials, missing privileges, or expired auth | | not_found | Requested VM, container, storage, or path does not exist | | timeout | Request or tool runtime timed out | | network | Connection failure to the Proxmox host | | server_error | Proxmox returned a server-side failure | | unknown | Unexpected error outside the known categories |

Errors in timeout, network, and server_error categories are marked retryable.

Tool catalog

Virtual Machines (QEMU/KVM)

| Tool | Description | |---|---| | proxmox_vm_list | List all VMs on a node | | proxmox_vm_status | Get detailed VM status and config | | proxmox_vm_config | Get VM configuration | | proxmox_vm_start | Start a VM | | proxmox_vm_stop | Force-stop a VM | | proxmox_vm_shutdown | Graceful ACPI shutdown | | proxmox_vm_reset | Hard-reset a VM | | proxmox_vm_resume | Resume a suspended VM | | proxmox_vm_suspend | Suspend a VM | | proxmox_vm_reboot | Reboot a VM | | proxmox_vm_create | Create a new VM | | proxmox_vm_delete | Delete a VM | | proxmox_vm_update_config | Update VM configuration | | proxmox_vm_template | Convert a stopped VM to a template | | proxmox_vm_move_disk | Move a VM disk to another storage | | proxmox_vm_pending_changes | List pending config changes | | proxmox_vm_snapshot | Snapshot a VM | | proxmox_vm_snapshot_list | List VM snapshots | | proxmox_vm_snapshot_rollback | Roll back to a VM snapshot | | proxmox_vm_snapshot_delete | Delete a VM snapshot | | proxmox_vm_clone | Clone a VM or template | | proxmox_vm_migrate | Migrate a VM to another node | | proxmox_vm_resize_disk | Resize a VM disk |

VM QEMU Guest Agent

| Tool | Description | |---|---| | proxmox_vm_agent_exec | Execute a command inside a VM | | proxmox_vm_agent_exec_status | Get execution status and output by PID | | proxmox_vm_agent_ping | Ping the guest agent | | proxmox_vm_agent_info | Get guest-agent version and supported commands | | proxmox_vm_agent_get_host_name | Get VM hostname | | proxmox_vm_agent_get_network_interfaces | Get VM network interfaces | | proxmox_vm_agent_get_osinfo | Get VM OS information | | proxmox_vm_agent_get_time | Get VM system time | | proxmox_vm_agent_get_users | List logged-in users | | proxmox_vm_agent_get_vcpus | Get VCPU info | | proxmox_vm_agent_file_read | Read a file from a VM | | proxmox_vm_agent_file_write | Write a file to a VM | | proxmox_vm_agent_set_user_password | Set a user's password inside a VM |

LXC Containers

| Tool | Description | |---|---| | proxmox_lxc_list | List containers on a node | | proxmox_lxc_status | Get container status and config | | proxmox_lxc_start | Start a container | | proxmox_lxc_stop | Stop a container | | proxmox_lxc_shutdown | Shut down a container | | proxmox_lxc_reset | Hard-reset a container | | proxmox_lxc_resume | Resume a suspended container | | proxmox_lxc_suspend | Suspend a container | | proxmox_lxc_reboot | Reboot a container | | proxmox_lxc_create | Create a container from template | | proxmox_lxc_delete | Delete a container | | proxmox_lxc_update_config | Update container configuration | | proxmox_lxc_template | Convert a stopped container to a template | | proxmox_lxc_template_list | List cached LXC templates | | proxmox_lxc_resize | Resize a mount point | | proxmox_lxc_pending_changes | List pending config changes | | proxmox_lxc_snapshot | Snapshot a container | | proxmox_lxc_snapshot_list | List container snapshots | | proxmox_lxc_snapshot_rollback | Roll back to a container snapshot | | proxmox_lxc_snapshot_delete | Delete a container snapshot | | proxmox_lxc_migrate | Migrate a container |

Nodes

| Tool | Description | |---|---| | proxmox_node_list | List cluster nodes | | proxmox_node_status | Get detailed node status | | proxmox_node_config | Get node configuration | | proxmox_node_services | List services on a node | | proxmox_node_service_status | Get detailed service status | | proxmox_node_service_start | Start a service | | proxmox_node_service_stop | Stop a service | | proxmox_node_service_restart | Restart a service | | proxmox_node_journal | Read systemd journal | | proxmox_node_dns | Get DNS configuration | | proxmox_node_time | Get system time and timezone | | proxmox_node_hardware | List hardware devices | | proxmox_node_network_list | List network interfaces | | proxmox_node_execute | Batch relative node API calls via /execute | | proxmox_node_reboot | Reboot the node | | proxmox_node_stop | Power off the node | | proxmox_node_apt_update | Refresh the APT package index | | proxmox_node_subscription | Get subscription status |

Storage and pools

| Tool | Description | |---|---| | proxmox_storage_list | List storage backends on a node | | proxmox_storage_content | List content on a storage backend | | proxmox_storage_create | Create a storage backend | | proxmox_storage_detail | Get storage details | | proxmox_storage_delete | Delete a storage backend | | proxmox_storage_scan | Scan for available storage resources | | proxmox_storage_upload | Download from URL and upload to Proxmox storage | | proxmox_storage_remove_volume | Remove a storage volume | | proxmox_pool_list | List resource pools | | proxmox_pool_create | Create a resource pool | | proxmox_pool_delete | Delete a resource pool |

Cluster

| Tool | Description | |---|---| | proxmox_cluster_status | Get cluster quorum and status | | proxmox_cluster_resources | List cluster resources | | proxmox_cluster_next_id | Get the next available VM or CT ID | | proxmox_cluster_version | Get Proxmox version information | | proxmox_cluster_log | Get the cluster log | | proxmox_cluster_options | Get cluster options | | proxmox_cluster_update_options | Update cluster options | | proxmox_cluster_config | Get cluster join configuration | | proxmox_check_permissions | Probe current token permissions |

Backup

| Tool | Description | |---|---| | proxmox_backup_list | List backup jobs | | proxmox_backup_create | Create a backup job | | proxmox_backup_delete | Delete a backup job |

Firewall

| Tool | Description | |---|---| | proxmox_firewall_rules | List firewall rules | | proxmox_firewall_rule_add | Add a firewall rule | | proxmox_firewall_rules_delete | Delete a firewall rule | | proxmox_firewall_options | Get firewall options | | proxmox_firewall_options_update | Update firewall options | | proxmox_firewall_aliases | List firewall aliases | | proxmox_firewall_alias_create | Create a firewall alias | | proxmox_firewall_alias_delete | Delete a firewall alias | | proxmox_firewall_ipset_list | List IPSets | | proxmox_firewall_ipset_create | Create an IPSet | | proxmox_firewall_ipset_delete | Delete an IPSet |

Access control

| Tool | Description | |---|---| | proxmox_user_list | List users | | proxmox_user_create | Create a user | | proxmox_user_detail | Get user details | | proxmox_user_delete | Delete a user | | proxmox_group_list | List groups | | proxmox_group_create | Create a group | | proxmox_group_delete | Delete a group | | proxmox_role_list | List roles | | proxmox_role_create | Create a role | | proxmox_role_delete | Delete a role | | proxmox_acl_list | List ACL entries | | proxmox_acl_update | Add or remove ACL entries | | proxmox_token_list | List API tokens for a user | | proxmox_token_create | Create an API token | | proxmox_token_delete | Delete an API token | | proxmox_domain_list | List authentication domains |

High availability

| Tool | Description | |---|---| | proxmox_ha_status | Get HA status | | proxmox_ha_resources_list | List HA resources | | proxmox_ha_resource_create | Add a resource to HA | | proxmox_ha_resource_delete | Remove a resource from HA | | proxmox_ha_groups_list | List HA groups | | proxmox_ha_group_create | Create an HA group | | proxmox_ha_group_delete | Delete an HA group |

Replication

| Tool | Description | |---|---| | proxmox_replication_list | List replication jobs | | proxmox_replication_create | Create a replication job | | proxmox_replication_delete | Delete a replication job | | proxmox_replication_run | Trigger replication sync | | proxmox_replication_log | Get replication job log |

Tasks

| Tool | Description | |---|---| | proxmox_task_list | List recent tasks | | proxmox_task_status | Get task status by UPID | | proxmox_task_log | Get task log output |

Universal API coverage

| Tool | Description | |---|---| | proxmox_api_call | Call any official GET/POST/PUT/DELETE endpoint under /api2/json | | proxmox_api_upload_file | Upload a local file to any multipart Proxmox upload endpoint |

Pagination notes

Several tools accept optional start and limit parameters. These map directly to Proxmox pagination or time-window query parameters.

| Tool | Endpoint | start semantics | |---|---|---| | proxmox_task_list | /nodes/{node}/tasks | integer offset | | proxmox_task_log | /nodes/{node}/tasks/{upid}/log | integer offset | | proxmox_node_journal | /nodes/{node}/journal | Unix timestamp |

For journal queries, start and end are epoch timestamps, not row offsets.

Repository layout

dist/                     Runtime extension code committed directly to the repo
  index.js                Pi extension entrypoint
  proxmox-client.js       REST client and auth logic
  tool-runtime.js         Shared tool execution helpers
  tools/                  Domain tool definitions

docs/                     Bundled Proxmox API reference material and operator docs

tests/                    Live integration, smoke, and runtime-behavior tests

scripts/                  Audit and maintenance helpers
.github/                  CI workflow, issue templates, and repo automation

README.md                 User-facing package documentation
AGENTS.md                 Agent/maintainer guidance
CONTRIBUTING.md           Contributor workflow
SECURITY.md               Security and disclosure policy
CHANGELOG.md              Release history

Compatibility

Verified directly from this repository:

| Component | Verified value | |---|---| | Pi runtime | 0.79.6 | | Proxmox VE release | 9.2 | | Proxmox VE version | 9.2.3 | | Node.js | >=22 |

See docs/COMPATIBILITY.md for the maintained compatibility notes.

Development

npm ci
npm test
npm run test:auth
npm run test:pagination
npm run test:vm-agent
npm run test:execute
npm run test:lxc
npm run test:vm
npm run test:upload
npm run test:runtime
npm run test:raw-api
npm run test:package
npm run test:security
npm run test:ci
npm run audit:official-api

Test philosophy

This project prefers real integration coverage over mock-heavy tests.

• API/auth behavior is tested against a real Proxmox host
• VM and LXC lifecycle tests create resources and clean them up
• Runtime tests verify Pi-specific behavior such as progress streaming, thrown tool errors, and tool timeout handling
• Raw API tests verify the universal coverage tools against official GET/POST/PUT/DELETE and upload-style endpoints
• Package tests verify repository metadata and published-package structure
• The official API audit script fetches the Proxmox API viewer and reports the current upstream route and method counts

CI security gates

GitHub Actions uses immutable action SHAs, npm ci for reproducible installs, runs npm audit --audit-level=high as part of npm run test:ci, performs GitHub dependency review on pull requests, and runs scheduled CodeQL analysis for the JavaScript codebase.

Publishing

npm pack --dry-run
npm publish --ignore-scripts

Publishing guidance, versioning rules, and release discipline live in AGENTS.md.

Support and feedback

The repository includes issue templates for:

• bug reports
• feature requests
• compatibility reports

When reporting problems, include the package version, Pi version, Proxmox version, tool name, and auth mode if possible.

See also

• AGENTS.md — maintainer and agent instructions
• CHANGELOG.md — release history
• CONTRIBUTING.md — contributor workflow
• SECURITY.md — security policy and disclosure instructions
• docs/API_COVERAGE_AUDIT.md — official API audit and coverage approach
• docs/COMPATIBILITY.md — verified environment notes
• docs/EXAMPLES.md — copyable usage examples
• docs/PERMISSIONS.md — auth and token guidance
• docs/TROUBLESHOOTING.md — common failure modes and fixes
• docs/ — bundled Proxmox reference material

License

MIT — see LICENSE.