Skip to main content

Proxmox

@dmc/proxmoxv2026.11.18.1· MIT· 3d agoBEHAVIORS
01README

Proxmox VE extensions with API-token auth and TLS verification — node status, cluster health and guest discovery, VM and CT snapshots through a least-privilege token, VM/LXC lifecycle (provisioning from cloud images, snapshots, migration), cloud image storage, and safe snapshot-guarded updates for community-scripts LXCs

02Release Notes

Breaking: ensureRunnerPoolAccess and its runnerPoolAccess and runnerPoolToken resources are removed. New ensureTokenAccess makes a least-privilege Proxmox API token from a policy the definition gives (user, token, pool role, other grants and templates, each with exact privileges; data {name}-access and {name}-token). It keeps every check of the old method and refuses privileges that change access or reach a node's shell. Migration: give the old roles and privileges with name runner-pool; a dry run must report unchanged. See the README section 'Upgrading to 2026.11.18.1'.

03Behaviors4
@dmc/proxmox/nodev2026.11.18.1proxmox_node.ts
fn status()
Fetch current node resource usage (memory, CPU, uptime). Needs: Sys.Audit on /nodes/{node}.
fn clusterHealth(node?: string)
Judge one node from /cluster/status: healthy when the node is listed and online and, in a cluster, the cluster is quorate. Read-only, and an unhealthy node is a result, not an error; a failed call or a malformed answer is an error. Needs: Sys.Audit on / (ensureSnapshotAccess with clusterAudit grants exactly that).
ArgumentTypeDescription
node?stringThe node to judge (default: the configured node)
fn listGuests()
List all VMs and CTs on the Proxmox cluster (type, vmid, name, status, node, ip). Needs: VM.Audit on each guest (others are not listed); VM.GuestAgent.Audit for VM IPs.
fn permissions()
Read the effective Proxmox privileges of the calling token/user (or of `userid`), optionally for one ACL path. Read-only. Needs: nothing for the caller itself; Sys.Audit on /access to read another user or token.
fn ensureSnapshotAccess(dryRun?: boolean, user?: string, tokenName?: string, clusterAudit?: boolean, pool?: string, members?: array)
Make a least-privilege Proxmox API token that may only snapshot, roll back and power the guests in one pool, and, with clusterAudit, read cluster health (Sys.Audit on / only, in its own role).
ArgumentTypeDescription
dryRun?booleanPlan and check only; write nothing (default true)
user?stringProxmox user that owns the snapshot token
tokenName?stringAPI token name under that user
clusterAudit?booleanAlso let the token read cluster health (/cluster/status: quorum and node membership, for the clusterHealth method): role auditRole, exactly Sys.Audit, on / with propagate 0, for the user and the token. Sys.Audit on / also reads cluster-level status and configuration (HA status, cluster options, firewall rules, backup and replication jobs). It gives no right on a node, guest, pool or storage path, and no write. Default false: the token holds the snapshot role only
pool?stringPool whose guests the token may snapshot, roll back and power
members?arrayGuests to put in the pool; never moved from another pool
fn ensureTokenAccess(dryRun?: boolean, name: string, user: string, tokenName: string, pool: object, members?: array, grants?: array, templates?: object, updateRoles?: boolean)
Make a least-privilege Proxmox API token from a policy the definition gives: one pool role on /pool/{pool} (its privileges hold on each guest in the pool), other grants each with its own custom role on one path, and a template role on each /vms/{template}. Every grant has propagate 0, and each role must hold exactly its privileges. The templates must exist, be templates and stay outside the pool. Privileges that change access or reach a node's shell (Permissions.Modify, User.Modify, Group.Alloca
ArgumentTypeDescription
dryRun?booleanPlan and check only; write nothing (default true)
namestringNames this token's data: the record {name}-access and the one-time secret {name}-token
userstringProxmox user that owns the token
tokenNamestringAPI token name under that user
poolobjectThe pool grant: role on /pool/{name}, to the user and the token
members?arrayGuests to put in the pool; never moved from another pool
grants?arrayOther grants, each its own custom role on one path
templates?objectTemplates the token may use: role on each /vms/{vmid}. Each must exist, be a template and stay outside the pool, so the pool role never reaches it
updateRoles?booleanAdd the missing privileges to an existing role (for example, after the policy adds one). A role with extra privileges still blocks the run. Default false: a role that is missing privileges blocks the run

Resources

status(infinite)— Node resource usage (memory, CPU, uptime)
guests(infinite)— VMs + CTs known to the Proxmox cluster
snapshot(infinite)— Result of a VM or CT snapshot / rollback / list / delete
permissions(infinite)— Effective Proxmox privileges of a token or user, per ACL path
snapshotAccess(infinite)— Plan, blockers, actions and verification of an ensureSnapshotAccess run
clusterHealth(infinite)— One node judged from /cluster/status: listed, online, cluster quorate
snapshotToken(infinite)— One-time secret of a snapshot API token created by ensureSnapshotAccess (sensitive)
tokenAccess(infinite)— Plan, blockers, actions and verification of an ensureTokenAccess run
accessToken(infinite)— One-time secret of an API token created by ensureTokenAccess (sensitive)
@dmc/proxmox/vmv2026.11.14.2proxmox_vm.ts
fn lookup()
Look up VM by name, return vmid and IP if running. Needs: VM.Audit; VM.GuestAgent.Audit for the IP.
fn start(waitSeconds?: number, pollInterval?: number, requireIp?: boolean)
Start VM if stopped (idempotent), wait for IP. Needs: VM.PowerMgmt, VM.Audit; VM.GuestAgent.Audit for the IP.
ArgumentTypeDescription
waitSeconds?numberMax seconds to wait for VM IP
pollInterval?numberSeconds between IP poll attempts
requireIp?booleanFail if the guest agent does not report an IP. Set false for VMs with no agent (e.g. booting an installer ISO).
fn stop()
Stop a VM by name. Needs: VM.PowerMgmt, VM.Audit.
fn create(memory?: number, cores?: number, sockets?: number, diskSize?: number, diskStorage?: string, networkBridge?: string, osType?: string)
Create a new VM with PXE boot enabled, auto-allocating vmid (no-op if a VM with that name exists). Needs: VM.Allocate, Datastore.AllocateSpace on the disk storage, SDN.Use on the bridge.
ArgumentTypeDescription
memory?numberMemory in MB (default 2048)
cores?numberCPU cores (default 2)
sockets?numberCPU sockets (default 1)
diskSize?numberDisk size in GB (default 32, 0 for PXE-only)
diskStorage?stringStorage pool (default 'local-lvm')
networkBridge?stringNetwork bridge (default 'vmbr0')
osType?stringOS type (default 'l26')
fn shutdown(timeoutSeconds?: number)
Shut a VM down cleanly (ACPI, or the guest agent when the VM has it on) and wait until it is stopped; no-op when it is stopped. Fails when the guest is still running after timeoutSeconds: it never forces a stop (stop does that). Needs: VM.PowerMgmt, VM.Audit.
ArgumentTypeDescription
timeoutSeconds?numberSeconds Proxmox waits for the guest to power off. When it is still running after that, the method fails; it never forces a stop (stop does that)
fn delete()
Stop (if running) and delete a VM by name (succeeds if already gone). Needs: VM.Allocate, VM.PowerMgmt, VM.Audit.
fn clone(source: string, vmName: string, newid?: number, pool?: string, linked?: boolean, storage?: string)
Clone a VM or template by name into a new VM, linked by default (the source must then be a template), optionally into a pool. No-op when a VM with the new name exists. Records how long the clone task took (durationMs). Needs: VM.Clone on the source; VM.Allocate on /vms/{newid} or on /pool/{pool}; Datastore.AllocateSpace on the target storage; SDN.Use on the bridge when Proxmox checks it.
ArgumentTypeDescription
sourcestringName of the VM or template to clone
vmNamestringName of the new VM
newid?numberVM id of the new VM (default: the next free id)
pool?stringPool to put the new VM in
linked?booleanLinked clone (default): the new disks are copy-on-write on the template's base disks; the source must be a template. False makes a full copy
storage?stringTarget storage of a full clone (default: the source's)
fn convertToTemplate()
Turn a stopped VM into a template (no-op when it is one). Refuses a VM that is not stopped; it never stops it. Needs: VM.Allocate, VM.Audit.
fn setBootOrder(boot: string)
Set VM boot order via Proxmox API. Needs: VM.Config.Options, VM.Audit.
ArgumentTypeDescription
bootstringBoot order string (e.g. 'order=scsi0;net0')
fn setConfig(config: record)
Set arbitrary VM config options via Proxmox API (e.g. agent, memory, cores). Needs: the matching VM.Config.* privilege, VM.Audit.
ArgumentTypeDescription
configrecordArbitrary VM config key/values for setConfig method
fn sync()
Sync all VMs from Proxmox — writes a named resource per VM. Needs: VM.Audit (only audited VMs are listed); VM.GuestAgent.Audit for IPs.

Resources

vm(infinite)— VM operation result
@dmc/proxmox/storagev2026.11.07.1proxmox_storage.ts

Global Arguments

ArgumentTypeDescription
apiUrlstringProxmox API base URL (e.g., https://192.0.2.10:8006)
nodestringProxmox node name
storagestringStorage name to download into (e.g., local)
skipTlsVerify?booleanSkip TLS certificate verification (curl -k). Ignored when caCert is set.
caCert?stringPEM CA certificate(s) that sign a self-signed API certificate (for a cluster, /etc/pve/pve-root-ca.pem). When set, every API call checks the certificate and host name with curl --cacert, and skipTlsVerify has no effect. Linux curl then trusts this CA only; the macOS system curl also keeps trusting the system roots. Not needed when the API has a publicly trusted certificate: set skipTlsVerify false instead.
tokenId?stringProxmox API token id, user@realm!tokenname (used with tokenSecret; the only auth)
tokenSecret?stringProxmox API token secret
fn downloadImage(url: string, filename: string, checksum?: string, checksumAlgorithm?: string)
Download a cloud image from a URL into Proxmox storage via the download-url API (Proxmox fetches directly — no local upload). Skips the download if the filename already exists in storage.
ArgumentTypeDescription
urlstringPublic URL of the image to download
filenamestringFilename to save as in storage (e.g., Rocky-9-GenericCloud-Base.latest.x86_64.qcow2)
checksum?stringExpected checksum value for integrity verification
checksumAlgorithm?stringChecksum algorithm (sha256, md5, sha1)

Resources

image(infinite)— Cloud image downloaded into Proxmox storage, ready for import-from
@dmc/proxmox/community-scriptv2026.11.03.1proxmox_community_script.ts

Global Arguments

ArgumentTypeDescription
sshModelstringName of the @swamp/ssh model instance used to reach the PVE node (required, no default)
node?stringFleet host name (a host in the sshModel) of the PVE hypervisor running the container, e.g. "pve1". Required with reach pct for every method except discoverApp/previewInstall (which only read the community-scripts sources).
reach?enumHow the container is reached: pct (default) runs every command as root through pct on `node`; ssh reaches the container itself (`ctHost`) as a non-root login, runs the update through `sudo -n` with one exact command (see the privileges method), and takes snapshots only through `nodeModel`
ctHost?stringWith reach ssh: the container's own host name in the sshModel (required there)
nodeModel?stringA @dmc/proxmox/node model whose API token may snapshot this CT. When set, snapshots, rollbacks, deletes and snapshot lists go through its snapshotCt / rollbackCt / deleteCtSnapshot / listCtSnapshots instead of pct. With reach ssh it is the only way to take a snapshot
ctid?numberLXC container ID, e.g. 601. Required for every method except discoverApp/previewInstall.
appName?stringHuman-readable app name for logs/output, e.g. "Forgejo"
service?stringsystemd unit inside the container to health-check, e.g. "forgejo". Required for every method except discoverApp/previewInstall.
serviceActiveCommand?stringCommand run inside the container (via `sh -c`) whose exit 0 means the service is up. Overrides the default `systemctl is-active <service>` — set this for non-systemd containers, e.g. Alpine/OpenRC: "rc-service <service> status".
updateCommand?stringCommand run inside the container (via `bash -lc`) to perform the update. Default runs the community-scripts helper in forced-silent mode (PHS_SILENT=1) so it never prompts. Add `var_ignore_os_mismatch=1` here to bypass the OS-version guard. With reach ssh it is not run by a shell: it must be `[NAME=value ...] /absolute/bin [args]` (values A-Za-z0-9._/:=+-), and runs as exactly that argv through `sudo -n` (env pairs through env).
versionCommand?stringOptional command run inside the container to capture a version string before/after, e.g. "forgejo --version"
versionRegex?stringRegex (first capture group) used to extract a comparable semver from the versionCommand output and the release tag
releaseApiUrl?stringOptional release API URL whose JSON `tag_name` is the latest upstream version, e.g. https://codeberg.org/api/v1/repos/forgejo/forgejo/releases/latest . When set, status/checkUpdate report whether an update is available.
osManaged?booleanTrue when the app binary is delivered by the container's OS package manager (apk/apt/dnf),
packageName?stringOS package to query for the available version when osManaged (apk/apt-cache/dnf). Defaults to `app` then `service`.
healthUrl?stringOptional HTTP(S) URL probed from the swamp host after update to confirm the app is serving
healthExpectStatus?numberHTTP status the healthUrl must return to be considered healthy
updateTimeoutSec?numberSeconds allowed for the in-container update command to finish
healthTimeoutSec?numberSeconds to wait for the app to become healthy again after update
pollIntervalSec?numberSeconds between health polls
app?stringcommunity-scripts app slug for the `install` method, e.g. "forgejo" (resolves to <ctScriptBaseUrl>/ct/<app>.sh). Only LXC (ct/*.sh) scripts support headless install; VM (vm/*.sh) scripts are interactive-only — use @dmc/proxmox/vm createFromImage instead.
ctScriptBaseUrl?stringBase URL for community-scripts; the LXC script is <ctScriptBaseUrl>/ct/<app>.sh and build.func is <ctScriptBaseUrl>/misc/build.func
installVars?recordFreeform community-scripts var_* overrides passed as env to the install (e.g. {"var_cpu":"2","var_ram":"2048","var_disk":"10","var_hostname":"forgejo"}). Keys must match var_[a-z0-9_]+. Validated (warn-only) against the var_* names discovered in build.func; the app\
installTimeoutSec?numberSeconds allowed for the community-scripts install to finish (downloads + builds)
fn status()
Report container running state, service health, version, and snapshots
fn discoverApp()
Read-only: discover the community-scripts app's default var_* settings (from its ct script) and the var_* names build.func recognizes, to help compose installVars. Requires `app`.
fn previewInstall()
Read-only: inspect the community-scripts ct + install scripts for `app` and summarize what installing it will do (provisioning defaults, narrated steps, packages, release downloads, services, exposed port) — run this before `install`. Requires `app`.
fn install(force?: boolean)
Provision a NEW community-scripts LXC headlessly at `ctid` (PHS_SILENT=1 mode=default, var_ctid pinned, installVars as env), then verify it comes up healthy. LXC only — VM (vm/*.sh) scripts are interactive-only; use @dmc/proxmox/vm createFromImage for VMs.
ArgumentTypeDescription
force?booleanProceed even if a container already exists at ctid (community-scripts will refuse to overwrite, but this bypasses the pre-check)
fn checkUpdate()
Report whether an upstream update is available (installed version vs releaseApiUrl tag), without changing anything
fn safeUpdate(force?: boolean, keepSnapshot?: boolean, snapshot?: boolean)
Snapshot the container, run the in-container update, validate health, and roll back to the snapshot if the app does not come back healthy (pass snapshot=false to skip the snapshot and rollback when the caller owns them)
ArgumentTypeDescription
force?booleanProceed even if the container is not healthy before the update
keepSnapshot?booleanKeep the pre-update snapshot after a successful update (false deletes it). Ignored when snapshot is false
snapshot?booleanTake a pre-update snapshot and roll back to it on failure (default). Pass false when the caller already holds its own snapshot and owns the rollback (for example @dmc/patch safeOsUpdate): no snapshot is taken, keepSnapshot is ignored, the update and health gate still run, and an unhealthy result is reported as a failure without any rollback
fn privileges(host?: string)
Declare the root commands the update needs, for @dmc/patch (the privileges({ host }) contract). Read-only: runs nothing on any host. reach ssh: the update as one exact argv run through sudo -n; it fetches and runs community-scripts code from ProxmoxVE and core, so remoteCode is true with both as remoteSources. reach pct: refused, because pct runs every command as root on the node and no sudo grant covers that.
ArgumentTypeDescription
host?stringThe @dmc/patch machine that asks; when set it must equal ctHost
fn rollback(snapshot?: string)
Roll the container back to a snapshot (named, or the most recent preupdate-* snapshot)
ArgumentTypeDescription
snapshot?stringSnapshot name to roll back to; defaults to the most recent preupdate-* snapshot

Resources

state(infinite)— Observed container + app health state
update(infinite)— Result of a safeUpdate run
updateCheck(infinite)— Installed vs latest upstream version and whether an update is available
install(infinite)— Result of an install run
discovery(infinite)— Discovered app defaults and recognized var_* names
preview(infinite)— Pre-install summary of what the community-scripts install will do
privileges(infinite)— The root commands the update needs (the @dmc/patch privileges contract)
04Previous Versions17
2026.11.15.1MIT

ensureRunnerPoolAccess: the pool role adds Pool.Audit, so the runner-pool token can read pool membership (without it /cluster/resources leaves out each guest's pool). A pool role made by an earlier release blocks the run until it is re-run with updateRoles: true.

2026.11.14.3MIT
2026.11.14.2MIT
2026.11.14.1MIT

Modified 1 behaviors

2026.11.13.1MIT

Modified 2 behaviors

2026.11.07.1MIT(was none)

Modified 2 behaviors. updated dependencies

2026.10.26.1

Added 2 behaviors

2026.10.25.1
2026.10.22.1
2026.10.01.1
2026.09.30.3
2026.09.30.2
2026.09.30.1
2026.09.18.1
2026.09.13.1

Added 1 behaviors. updated dependencies

2026.07.18.1
2026.06.30.1
05Stats
A
100 / 100
Downloads
106
Archive size
137.5 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels