proxmox-ve

n8n community nodes for Proxmox VE: nodes, VMs, containers, guest agent, storage, backups, cluster, HA, tasks and a polling trigger.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.2.1
Author: FDalCol

Documentation

n8n-nodes-proxmox-ve

npm version
npm downloads
license

n8n community nodes for Proxmox VE:
manage nodes, VMs, containers, storage, backups, HA and tasks, and start workflows on
Proxmox VE events.

  • Proxmox VE: action node, usable as an AI agent tool
  • Proxmox VE Trigger: polling trigger

Requires n8n 2.45.0 or later. Tested with Proxmox VE 9.x; 8.4 support is based on the
official API specification.

Installation

From npm: Settings → Community Nodes → Install → n8n-nodes-proxmox-ve.

Manual (Docker): replace n8n with your container name.

docker cp n8n-nodes-proxmox-ve-0.2.1.tgz n8n:/tmp/
docker exec -it n8n sh -c "mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes && npm install --legacy-peer-deps /tmp/n8n-nodes-proxmox-ve-0.2.1.tgz"
docker restart n8n

Credentials

Field Notes
Base URL e.g. https://pve.example.com:8006
Authentication API Token (recommended) or Username/Password (no 2FA)
Token ID / Secret user@realm!tokenid and its secret
Allow Self-Signed Certificate Skips certificate validation; the connection stays on HTTPS
Allow Insecure HTTP Trusted lab networks only. Off by default

Use a read-only token for reads and the trigger, and a separate token for writes,
limited to what your workflows need:

pveum user add n8n@pve
pveum user token add n8n@pve readonly --privsep 1
pveum acl modify / --tokens 'n8n@pve!readonly' --roles PVEAuditor
pveum user token add n8n@pve ops --privsep 1
pveum acl modify /vms --tokens 'n8n@pve!ops' --roles PVEVMUser

PVEAuditor is not enough for updates (Sys.Modify), syslog and journal
(Sys.Syslog) and the guest agent (VM.GuestAgent.* on 9.x, VM.Monitor on 8.x).

With an administrative token, an AI agent can shut down nodes, delete VMs or run
commands inside guests. Give agents a read-only token unless writes are needed.

Operations

Resource Operations
Node Get Many, Get Status, Shutdown, Reboot, Wake On LAN, Start/Stop/Suspend All Guests, Services, Updates, Package Versions, Syslog, Journal, Network, Disks, SMART, Certificates, RRD Data
VM Get Many, Get, Status, Config, Pending, Create, Update Config, Delete, Start, Stop, Shutdown, Reboot, Reset, Suspend, Hibernate, Resume, Clone, Migrate, Convert To Template, Resize Disk, Move Disk, RRD Data, Snapshots, Cloud-Init, Next Free VMID
Container Same as VM where available (no Reset, Hibernate, Cloud-Init)
Guest Agent Ping, Info, OS Info, Network Interfaces, Filesystems, Exec, File Read, File Write, FS Freeze/Thaw, Shutdown
Storage Get Many, Status, Content, Upload, Download From URL, Allocate Volume, Delete Volume, RRD Data
Backup Create, Get Many, Delete, Prune (preview unless Delete Backups is set), Not Backed Up Guests
Backup Job Get, Get Many, Run Now
Cluster Status, Resources, Log, Options, Version
High Availability Resources, Rules (9.x), Groups (8.x), Status
Pool Get Many, Create, Update, Delete
Replication Get Many, Get, Create, Update, Delete, Run Now
Access Users, Groups, Roles, ACL, Effective Permissions, API Tokens (read-only, never secrets)
Task Get Many, Get Last, Status, Log, Stop, Wait For Completion
Custom API Call Any method on a path below /api2/json

Operations that start a Proxmox task return its UPID and offer Wait For Completion,
which fails the node if the task fails. Lists support Split Into Items. For
endpoints not covered, use Custom API Call with the
API Viewer.

Trigger

Event Fires when
Guest State Changed a VM or container becomes running, stopped or paused
Node Status Changed a node goes online or offline
Task Finished a task ends, optionally only with errors (e.g. a failed backup)
Storage Usage Above Threshold usage reaches the threshold, once until it drops below
Updates Available a node has new upgradable packages

The first poll stores the current state without emitting events.

{
  "event": "taskFinished",
  "type": "vzdump",
  "node": "pve1",
  "status": "job errors",
  "success": false,
  "upid": "UPID:pve1:0001A2B3:00C4D5E6:6790ABCD:vzdump::root@pam:"
}

Security

  • HTTPS by default, never downgraded; redirects are not followed.
  • Token secrets, tickets and CSRF tokens never appear in URLs, outputs or errors; the
    password is only sent in the login request.
  • Path values are validated; Custom API Call stays inside /api2/json.
  • Requests time out after 30 s without data (30 min for uploads); responses over 32 MiB
    are aborted.

Support

If this node saves you time, you can buy me a coffee.

License

MIT. Proxmox is a registered trademark of Proxmox Server Solutions GmbH;
this project is not affiliated with or endorsed by it.

Discussion