@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 .

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 install
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: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

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.