Proxmox
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
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'.
| Argument | Type | Description |
|---|---|---|
| node? | string | The node to judge (default: the configured node) |
| Argument | Type | Description |
|---|---|---|
| dryRun? | boolean | Plan and check only; write nothing (default true) |
| user? | string | Proxmox user that owns the snapshot token |
| tokenName? | string | API token name under that user |
| clusterAudit? | boolean | Also 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? | string | Pool whose guests the token may snapshot, roll back and power |
| members? | array | Guests to put in the pool; never moved from another pool |
| Argument | Type | Description |
|---|---|---|
| dryRun? | boolean | Plan and check only; write nothing (default true) |
| name | string | Names this token's data: the record {name}-access and the one-time secret {name}-token |
| user | string | Proxmox user that owns the token |
| tokenName | string | API token name under that user |
| pool | object | The pool grant: role on /pool/{name}, to the user and the token |
| members? | array | Guests to put in the pool; never moved from another pool |
| grants? | array | Other grants, each its own custom role on one path |
| templates? | object | Templates 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? | boolean | Add 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
| Argument | Type | Description |
|---|---|---|
| waitSeconds? | number | Max seconds to wait for VM IP |
| pollInterval? | number | Seconds between IP poll attempts |
| requireIp? | boolean | Fail if the guest agent does not report an IP. Set false for VMs with no agent (e.g. booting an installer ISO). |
| Argument | Type | Description |
|---|---|---|
| memory? | number | Memory in MB (default 2048) |
| cores? | number | CPU cores (default 2) |
| sockets? | number | CPU sockets (default 1) |
| diskSize? | number | Disk size in GB (default 32, 0 for PXE-only) |
| diskStorage? | string | Storage pool (default 'local-lvm') |
| networkBridge? | string | Network bridge (default 'vmbr0') |
| osType? | string | OS type (default 'l26') |
| Argument | Type | Description |
|---|---|---|
| timeoutSeconds? | number | Seconds 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) |
| Argument | Type | Description |
|---|---|---|
| source | string | Name of the VM or template to clone |
| vmName | string | Name of the new VM |
| newid? | number | VM id of the new VM (default: the next free id) |
| pool? | string | Pool to put the new VM in |
| linked? | boolean | Linked 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? | string | Target storage of a full clone (default: the source's) |
| Argument | Type | Description |
|---|---|---|
| boot | string | Boot order string (e.g. 'order=scsi0;net0') |
| Argument | Type | Description |
|---|---|---|
| config | record | Arbitrary VM config key/values for setConfig method |
Resources
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiUrl | string | Proxmox API base URL (e.g., https://192.0.2.10:8006) |
| node | string | Proxmox node name |
| storage | string | Storage name to download into (e.g., local) |
| skipTlsVerify? | boolean | Skip TLS certificate verification (curl -k). Ignored when caCert is set. |
| caCert? | string | PEM 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? | string | Proxmox API token id, user@realm!tokenname (used with tokenSecret; the only auth) |
| tokenSecret? | string | Proxmox API token secret |
| Argument | Type | Description |
|---|---|---|
| url | string | Public URL of the image to download |
| filename | string | Filename to save as in storage (e.g., Rocky-9-GenericCloud-Base.latest.x86_64.qcow2) |
| checksum? | string | Expected checksum value for integrity verification |
| checksumAlgorithm? | string | Checksum algorithm (sha256, md5, sha1) |
Resources
Global Arguments
| Argument | Type | Description |
|---|---|---|
| sshModel | string | Name of the @swamp/ssh model instance used to reach the PVE node (required, no default) |
| node? | string | Fleet 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? | enum | How 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? | string | With reach ssh: the container's own host name in the sshModel (required there) |
| nodeModel? | string | A @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? | number | LXC container ID, e.g. 601. Required for every method except discoverApp/previewInstall. |
| appName? | string | Human-readable app name for logs/output, e.g. "Forgejo" |
| service? | string | systemd unit inside the container to health-check, e.g. "forgejo". Required for every method except discoverApp/previewInstall. |
| serviceActiveCommand? | string | Command 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? | string | Command 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? | string | Optional command run inside the container to capture a version string before/after, e.g. "forgejo --version" |
| versionRegex? | string | Regex (first capture group) used to extract a comparable semver from the versionCommand output and the release tag |
| releaseApiUrl? | string | Optional 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? | boolean | True when the app binary is delivered by the container's OS package manager (apk/apt/dnf), |
| packageName? | string | OS package to query for the available version when osManaged (apk/apt-cache/dnf). Defaults to `app` then `service`. |
| healthUrl? | string | Optional HTTP(S) URL probed from the swamp host after update to confirm the app is serving |
| healthExpectStatus? | number | HTTP status the healthUrl must return to be considered healthy |
| updateTimeoutSec? | number | Seconds allowed for the in-container update command to finish |
| healthTimeoutSec? | number | Seconds to wait for the app to become healthy again after update |
| pollIntervalSec? | number | Seconds between health polls |
| app? | string | community-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? | string | Base URL for community-scripts; the LXC script is <ctScriptBaseUrl>/ct/<app>.sh and build.func is <ctScriptBaseUrl>/misc/build.func |
| installVars? | record | Freeform 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? | number | Seconds allowed for the community-scripts install to finish (downloads + builds) |
| Argument | Type | Description |
|---|---|---|
| force? | boolean | Proceed even if a container already exists at ctid (community-scripts will refuse to overwrite, but this bypasses the pre-check) |
| Argument | Type | Description |
|---|---|---|
| force? | boolean | Proceed even if the container is not healthy before the update |
| keepSnapshot? | boolean | Keep the pre-update snapshot after a successful update (false deletes it). Ignored when snapshot is false |
| snapshot? | boolean | Take 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 |
| Argument | Type | Description |
|---|---|---|
| host? | string | The @dmc/patch machine that asks; when set it must equal ctHost |
| Argument | Type | Description |
|---|---|---|
| snapshot? | string | Snapshot name to roll back to; defaults to the most recent preupdate-* snapshot |
Resources
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.
Modified 1 behaviors
Modified 2 behaviors
Modified 2 behaviors. updated dependencies
Added 2 behaviors
Added 1 behaviors. updated dependencies
- 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