Proxmox
@dmc/proxmoxv2026.10.01.1
01README
Proxmox VE extensions — VM/LXC lifecycle operations, cloud image storage, and safe snapshot-guarded updates for community-scripts LXCs
02Models
@dmc/proxmox/storagev2026.07.18.1proxmox_storage.ts
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 |
| ticket? | string | Auth ticket from proxmox-node |
| csrfToken? | string | CSRF token from proxmox-node |
| username? | string | Proxmox username (fallback auth) |
| password? | string | Proxmox password (fallback auth) |
| realm | string | Authentication realm |
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.
| 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
image(infinite)— Cloud image downloaded into Proxmox storage, ready for import-from
@dmc/proxmox/community-scriptv2026.09.30.1proxmox_community_script.ts
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 for every method except discoverApp/previewInstall (which only read the community-scripts sources). |
| 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. |
| 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) |
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.
| 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) |
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)
| 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 |
fn rollback()
Roll the container back to a snapshot (named, or 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
03Previous Versions
2026.09.30.3
2026.09.30.2
2026.09.30.1
2026.09.18.1
2026.09.13.1
Added 1 models. updated dependencies
2026.07.18.1
2026.06.30.1
04Stats
A
100 / 100
Downloads
25
Archive size
67.0 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
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
05Platforms
06Labels