Skip to main content

Proxmox

@keeb/proxmoxv2026.10.15.2· 1mo agoBEHAVIORSWORKFLOWSSKILLSACCEPTED WARNINGS
01README

Proxmox API auth + VM fleet lifecycle management (https://github.com/keeb/swamp-proxmox)

02Behaviors2
@keeb/proxmox/nodev2026.05.26.1proxmox_node.ts

Global Arguments

ArgumentTypeDescription
apiUrlstringProxmox API base URL (e.g., https://192.0.2.10:8006)
username?stringProxmox username for authentication
password?stringProxmox password for authentication (use a vault reference)
realm?stringAuthentication realm (pam, pve, etc.)
nodestringProxmox node name
skipTlsVerify?booleanSkip TLS certificate verification
fn auth()
Authenticate with Proxmox and return ticket/csrfToken
fn status()
Fetch current node resource usage (memory, CPU, uptime)
fn storageList()
List storage pools on the node — writes a named resource per storage
fn isoList(storage: string)
List ISO images on a storage — writes a named resource per ISO
ArgumentTypeDescription
storagestringStorage to list ISO content from
fn downloadIso(storage: string, url: string, filename: string, checksum?: string, checksumAlgorithm?: enum, verifyCertificates?: boolean)
Download an ISO from a URL directly onto a Proxmox storage (server-side)
ArgumentTypeDescription
storagestringTarget storage (must allow 'iso' content)
urlstringHTTP(S) URL to download the ISO from
filenamestringDestination filename, must end in .iso
checksum?stringExpected checksum of the image
checksumAlgorithm?enumChecksum algorithm (md5, sha1, sha224, sha256, sha384, sha512)
verifyCertificates?booleanVerify TLS certificates of the download URL

Resources

node(infinite)— Auth tokens for Proxmox node
status(infinite)— Node resource usage (memory, CPU, uptime)
storage(infinite)— Storage pool available on the node
iso(infinite)— ISO image present on a storage
@keeb/proxmox/vmv2026.05.26.1proxmox_vm.ts

Global Arguments

ArgumentTypeDescription
apiUrlstringProxmox API base URL (e.g., https://192.0.2.10:8006)
ticket?stringAuth ticket, usually wired from the node model's `node` resource
csrfToken?stringCSRF token, usually wired from the node model's `node` resource
nodestringProxmox node name
skipTlsVerify?booleanSkip TLS certificate verification
fn lookup(vmName: string)
Look up VM by name, return vmid and IP if running
ArgumentTypeDescription
vmNamestringVM name to manage
fn start(vmName: string, waitSeconds?: number, pollInterval?: number, requireIp?: boolean)
Start VM if stopped (idempotent), wait for IP. Replaces ensureVmRunning.
ArgumentTypeDescription
vmNamestringVM name to manage
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(vmName: string)
Stop a VM by name
ArgumentTypeDescription
vmNamestringVM name to manage
fn create(vmName: string, 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)
ArgumentTypeDescription
vmNamestringVM name to manage
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 delete(vmName: string)
Stop (if running) and delete a VM by name (succeeds if already gone)
ArgumentTypeDescription
vmNamestringVM name to manage
fn setBootOrder(vmName: string, boot: string)
Set VM boot order via Proxmox API
ArgumentTypeDescription
vmNamestringVM name to manage
bootstringBoot order string (e.g. 'order=scsi0;net0')
fn setConfig(vmName: string, config: record)
Set arbitrary VM config options via Proxmox API (e.g. agent, memory, cores)
ArgumentTypeDescription
vmNamestringVM name to manage
configrecordArbitrary VM config key/values for setConfig method
fn spiceConnect(vmName: string, outputPath?: string, proxyHost?: string)
Generate a virt-viewer .vv file for the VM's SPICE console (requires a SPICE-capable display type)
ArgumentTypeDescription
vmNamestringVM name to manage
outputPath?stringWhere to write the .vv connection file (default <repoDir>/spice/<vmName>.vv)
proxyHost?stringOverride the SPICE proxy host. Proxmox advertises its own node FQDN (often an unresolvable .local name); defaults to the host from apiUrl.
fn sync()
Sync all VMs from Proxmox — writes a named resource per VM

Resources

vm(infinite)— VM operation result
spice(infinite)— SPICE console connection details for a VM
03Workflows7
@keeb/sync-fleetf500c507-6d23-4d89-9d2a-c1d01d250a34

Authenticate with Proxmox and sync all VMs into the fleet

syncAuthenticate and sync all VMs from Proxmox into fleet
1.authkeebDev02.auth— Authenticate with Proxmox via keebDev02
2.sync-fleetfleet.sync— List all QEMU VMs and write per-VM named resources
@keeb/start-vm8a929a75-f1b5-4791-ba95-7ddebf97ac2e

Start a VM by name (idempotent, waits for IP)

start
1.authkeebDev02.auth
2.start-vmfleet.start
@keeb/stop-vme66c42ab-863a-42de-ae12-eb76753b0fcb

Stop a VM by name

stop
1.authkeebDev02.auth
2.stop-vmfleet.stop
@keeb/create-vmdfb23a92-2494-4b21-a9e1-ab75bed4ff46

Create a new VM by name (PXE boot, default specs)

create
1.authkeebDev02.auth
2.create-vmfleet.create
@keeb/delete-vm68178fcb-e2e3-4b05-b2ec-2f61a4e34997

Delete a VM by name (stops if running, then deletes)

delete
1.authkeebDev02.auth
2.delete-vmfleet.delete
@keeb/vm-lifecycle-test361565ac-f973-4b5a-b915-dbdfc9fb70fd

Test VM lifecycle - create, start, stop, delete using fleet with inputs

lifecycleComplete VM lifecycle test
1.authkeebDev02.auth— Authenticate with Proxmox
2.create-vmfleet.create— Create a test VM with PXE boot
3.start-vmfleet.start— Start the created VM
4.stop-vmfleet.stop— Stop the running VM
5.delete-vmfleet.delete— Delete the test VM
@keeb/guest-agent-test371d7d5e-8e75-462e-a410-2475f368f3bc

Test guest agent - create VM, start (validates agent via IP fetch), cleanup

guest-agentCreate VM, start (validates guest agent by fetching IP), cleanup
1.authkeebDev02.auth— Authenticate with Proxmox
2.create-vmfleet.create— Create a test VM with agent:1 and PXE boot (no disk)
3.start-vmfleet.start— Start the VM and wait for guest agent IP
4.stop-vmfleet.stop— Stop the test VM
5.delete-vmfleet.delete— Delete the test VM
04Skills1
proxmox1 file
05Previous Versions10
2026.10.15.1
2026.07.18.1
2026.05.26.1
2026.05.25.1
2026.04.22.3
2026.04.22.2
2026.03.02.3
2026.03.02.2
2026.03.02.1
2026.02.27.1
06Stats
A
93 / 100
Downloads
257
Archive size
41.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
  • License1/2partial

    no SPDX license declared

  • Verified public repository2/2earned

08Platforms
09Labels