Libvirt

@bad-at-naming/libvirtv2026.08.19.1· 3d agoMODELS

01README

Comprehensive libvirt/virsh management — VMs, networks, storage pools, volumes, snapshots, and host info — over SSH OR locally via a connection URI.

Connection modes (per model instance):

SSH mode: set host (+ optional user) and virsh runs on the remote hypervisor over ssh. No local libvirt client needed.
Local/URI mode: omit host and virsh runs on the swamp host against uri (default qemu:///system; supports qemu+ssh://, qemu+tls://, qemu:///session, etc.).

Models:

@bad-at-naming/libvirt/vm — domain lifecycle, tuning, monitoring, snapshots, guest agent
@bad-at-naming/libvirt/network — virtual network lifecycle + DHCP leases
@bad-at-naming/libvirt/storage — storage pool and volume management
@bad-at-naming/libvirt/host — hypervisor host info, capabilities, node stats

Local/URI connection support is merged from @evrardjp's fork (github.com/evrardjp/swamp-local-libvirt) — see README for credit.

02Models4

@bad-at-naming/libvirt/vmv2026.08.19.1extensions/models/libvirt_vm.ts

Global Arguments

Argument	Type	Required	Description
host?	string	no	SSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode.
user	string	yes	SSH username (SSH mode only; default: root)
uri?	string	no	Libvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set.

fn list()

List all VMs with state, vCPUs, memory, and autostart

fn get(name: string)

Get detailed VM info including disks, NICs, and graphics

Argument	Type	Required	Description
name	string	yes	VM name

fn dumpxml(name: string)

Get raw XML definition of a VM

Argument	Type	Required	Description
name	string	yes	VM name

fn start(name: string)

Start a VM. Idempotent — succeeds if already running.

Argument	Type	Required	Description
name	string	yes	VM name

fn stop(name: string)

Gracefully shut down a VM (ACPI) and wait until it is actually shut off before returning. Idempotent — succeeds if already stopped.

Argument	Type	Required	Description
name	string	yes	VM name

fn forceStop(name: string)

Force stop a VM (pull the power cord). Idempotent — succeeds if already stopped.

Argument	Type	Required	Description
name	string	yes	VM name

fn restart(name: string)

Reboot a running VM

Argument	Type	Required	Description
name	string	yes	VM name

fn reset(name: string)

Hard reset a VM (no ACPI, immediate reset)

Argument	Type	Required	Description
name	string	yes	VM name

fn suspend(name: string)

Suspend (pause) a running VM

Argument	Type	Required	Description
name	string	yes	VM name

fn resume(name: string)

Resume a suspended (paused) VM

Argument	Type	Required	Description
name	string	yes	VM name

fn autostart(name: string, enabled: boolean)

Enable or disable autostart for a VM

Argument	Type	Required	Description
name	string	yes	VM name
enabled	boolean	yes	true to enable, false to disable

fn define(xml: string)

Define a VM from XML. Idempotent: undefines an existing domain of the same name first, then redefines.

Argument	Type	Required	Description
xml	string	yes	Full libvirt domain XML definition

fn undefine(name: string, removeStorage: boolean, snapshotsMetadata: boolean, nvram: boolean)

Undefine a VM (remove its persistent configuration)

Argument	Type	Required	Description
name	string	yes	VM name
removeStorage	boolean	yes	Also remove all associated storage volumes
snapshotsMetadata	boolean	yes	Also remove snapshot metadata
nvram	boolean	yes	Also remove NVRAM file (required for UEFI VMs)

fn rename(name: string, newName: string)

Rename a VM (must be shut off)

Argument	Type	Required	Description
name	string	yes	Current VM name
newName	string	yes	New VM name

fn save(name: string, file: string)

Save VM state to a file (like hibernate)

Argument	Type	Required	Description
name	string	yes	VM name
file	string	yes	Path on hypervisor to save state to

fn restore(file: string)

Restore a VM from a saved state file

Argument	Type	Required	Description
file	string	yes	Path on hypervisor to restore from

fn setVcpus(name: string, count: number, maximum: boolean, config: boolean, live: boolean)

Change the number of virtual CPUs

Argument	Type	Required	Description
name	string	yes	VM name
count	number	yes	Number of vCPUs
maximum	boolean	yes	Set maximum vCPU count instead of current
config	boolean	yes	Apply to persistent config (next boot)
live	boolean	yes	Apply to running VM (hotplug)

fn setMemory(name: string, sizeMB: number, maximum: boolean, config: boolean, live: boolean)

Change memory allocation (in MiB)

Argument	Type	Required	Description
name	string	yes	VM name
sizeMB	number	yes	Memory in MiB
maximum	boolean	yes	Set maximum memory instead of current
config	boolean	yes	Apply to persistent config
live	boolean	yes	Apply to running VM

fn attachDisk(name: string, source: string, target: string, driver: enum, cache?: enum, persistent: boolean, config: boolean)

Attach a disk device to a VM

Argument	Type	Required	Description
name	string	yes	VM name
source	string	yes	Disk source path (image file or block device)
target	string	yes	Target device name (e.g. vdb, sdb)
driver	enum	yes	Disk driver/format
cache?	enum	no	Cache mode
persistent	boolean	yes	Make change persistent across reboots (running VMs)
config	boolean	yes	Apply to persistent config only (stopped VMs)

fn detachDisk(name: string, target: string, persistent: boolean, config: boolean)

Detach a disk device from a VM. Idempotent: succeeds if disk not found.

Argument	Type	Required	Description
name	string	yes	VM name
target	string	yes	Target device name to detach (e.g. vdb)
persistent	boolean	yes	Make change persistent (running VMs)
config	boolean	yes	Apply to persistent config only (stopped VMs)

fn attachInterface(name: string, type: enum, source: string, model: string, persistent: boolean)

Attach a network interface to a VM

Argument	Type	Required	Description
name	string	yes	VM name
type	enum	yes	Interface type
source	string	yes	Source bridge/network name (e.g. br0, default)
model	string	yes	NIC model (virtio, e1000, rtl8139)
persistent	boolean	yes	Make change persistent

fn detachInterface(name: string, type: enum, mac: string, persistent: boolean)

Detach a network interface from a VM by MAC address

Argument	Type	Required	Description
name	string	yes	VM name
type	enum	yes	Interface type
mac	string	yes	MAC address of the interface to detach
persistent	boolean	yes	Make change persistent

fn changeMedia(name: string, target: string, source?: string)

Change CD/DVD media for a VM

Argument	Type	Required	Description
name	string	yes	VM name
target	string	yes	Target device (e.g. hda, sda)
source?	string	no	New ISO path (omit to eject)

fn blockList(name: string)

List all block devices for a VM

Argument	Type	Required	Description
name	string	yes	VM name

fn interfaceList(name: string)

List all network interfaces for a VM

Argument	Type	Required	Description
name	string	yes	VM name

fn interfaceAddresses(name: string, source: enum)

Get IP addresses of a VM's interfaces

Argument	Type	Required	Description
name	string	yes	VM name
source	enum	yes	Address source: lease (DHCP), agent (guest-agent), arp

fn blockStats(name: string, device?: string)

Get block device I/O statistics for a VM

Argument	Type	Required	Description
name	string	yes	VM name
device?	string	no	Specific block device (e.g. vda). Omit for all.

fn interfaceStats(name: string, interface: string)

Get network interface statistics for a VM

Argument	Type	Required	Description
name	string	yes	VM name
interface	string	yes	Interface device name (e.g. vnet0)

fn memoryStats(name: string)

Get memory statistics for a VM

Argument	Type	Required	Description
name	string	yes	VM name

fn cpuStats(name: string)

Get CPU statistics for a VM

Argument	Type	Required	Description
name	string	yes	VM name

fn domstats(name: string)

Get comprehensive statistics for a VM (state, CPU, balloon, vCPU, net, block)

Argument	Type	Required	Description
name	string	yes	VM name

fn snapshotList(name: string)

List all snapshots for a VM

Argument	Type	Required	Description
name	string	yes	VM name

fn snapshotCreate(name: string, snapshotName: string, description?: string, quiesce: boolean, diskOnly: boolean)

Create a snapshot of a VM

Argument	Type	Required	Description
name	string	yes	VM name
snapshotName	string	yes	Name for the snapshot
description?	string	no	Snapshot description
quiesce	boolean	yes	Quiesce guest filesystem (requires guest agent)
diskOnly	boolean	yes	Disk-only snapshot (no memory)

fn snapshotInfo(name: string, snapshotName: string)

Get info about a specific snapshot

Argument	Type	Required	Description
name	string	yes	VM name
snapshotName	string	yes	Snapshot name

fn snapshotRevert(name: string, snapshotName: string, running: boolean, paused: boolean)

Revert a VM to a snapshot

Argument	Type	Required	Description
name	string	yes	VM name
snapshotName	string	yes	Snapshot name to revert to
running	boolean	yes	Start VM after revert
paused	boolean	yes	Leave VM paused after revert

fn snapshotDelete(name: string, snapshotName: string, children: boolean)

Delete a snapshot

Argument	Type	Required	Description
name	string	yes	VM name
snapshotName	string	yes	Snapshot name to delete
children	boolean	yes	Also delete child snapshots

fn snapshotDumpxml(name: string, snapshotName: string)

Get raw XML of a snapshot

Argument	Type	Required	Description
name	string	yes	VM name
snapshotName	string	yes	Snapshot name

fn guestInfo(name: string, types?: string)

Query guest information via QEMU guest agent (hostname, OS, IPs, filesystems, etc.)

Argument	Type	Required	Description
name	string	yes	VM name
types?	string	no	Comma-separated types: users, os, timezone, hostname, filesystem, disk, interface (omit for all)

fn setUserPassword(name: string, username: string, password: string, encrypted: boolean)

Set a user password inside the guest (requires guest agent). NOTE: the password is passed as a virsh argument and is visible in the hypervisor's process list while running — see README limitations.

Argument	Type	Required	Description
name	string	yes	VM name
username	string	yes	Username inside the guest
password	string	yes	New password
encrypted	boolean	yes	Password is already encrypted/hashed

Resources

vm(infinite)— VM list or detail

actionResult(1h)— Result of a VM action (start, stop, etc.)

snapshot(infinite)— Snapshot list or detail

stats(1h)— VM statistics (block, interface, memory, CPU)

@bad-at-naming/libvirt/networkv2026.08.19.1extensions/models/libvirt_network.ts

Global Arguments

Argument	Type	Required	Description
host?	string	no	SSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode.
user	string	yes	SSH username (SSH mode only; default: root)
uri?	string	no	Libvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set.

fn list()

List all virtual networks

fn get(name: string)

Get detailed info for a virtual network including XML config

Argument	Type	Required	Description
name	string	yes	Network name

fn dumpxml(name: string)

Get raw XML definition of a network

Argument	Type	Required	Description
name	string	yes	Network name

fn start(name: string)

Start (activate) a virtual network. Idempotent — succeeds if already active.

Argument	Type	Required	Description
name	string	yes	Network name

fn stop(name: string)

Stop (deactivate) a virtual network. Idempotent — succeeds if already inactive.

Argument	Type	Required	Description
name	string	yes	Network name

fn define(xml: string)

Define a virtual network from XML (does not start it)

Argument	Type	Required	Description
xml	string	yes	Full libvirt network XML definition

fn undefine(name: string)

Undefine a virtual network (remove persistent config)

Argument	Type	Required	Description
name	string	yes	Network name

fn autostart(name: string, enabled: boolean)

Enable or disable autostart for a virtual network

Argument	Type	Required	Description
name	string	yes	Network name
enabled	boolean	yes	true to enable, false to disable

fn dhcpLeases(name: string)

List DHCP leases for a virtual network

Argument	Type	Required	Description
name	string	yes	Network name

Resources

network(infinite)— Virtual network list or detail

dhcpLeases(1h)— DHCP leases for a network

actionResult(1h)— Result of a network action

@bad-at-naming/libvirt/storagev2026.08.19.1extensions/models/libvirt_storage.ts

Global Arguments

Argument	Type	Required	Description
host?	string	no	SSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode.
user	string	yes	SSH username (SSH mode only; default: root)
uri?	string	no	Libvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set.

fn poolList()

List all storage pools

fn poolGet(name: string)

Get detailed info for a storage pool including XML

Argument	Type	Required	Description
name	string	yes	Pool name

fn poolStart(name: string)

Start (activate) a storage pool. Idempotent: succeeds if already active.

Argument	Type	Required	Description
name	string	yes	Pool name

fn poolBuild(name: string)

Build a storage pool (creates target directory for dir pools)

Argument	Type	Required	Description
name	string	yes	Pool name

fn poolStop(name: string)

Stop (deactivate) a storage pool

Argument	Type	Required	Description
name	string	yes	Pool name

fn poolDefine(name: string, type: enum, target?: string, sourceHost?: string, sourcePath?: string, sourceFormat?: string)

Define a storage pool from parameters. Idempotent: succeeds if pool already exists.

Argument	Type	Required	Description
name	string	yes	Pool name
type	enum	yes	Pool type
target?	string	no	Target path (e.g. /var/lib/libvirt/images)
sourceHost?	string	no	Source host for network pools
sourcePath?	string	no	Source path/name
sourceFormat?	string	no	Source format (e.g. nfs, cifs, auto)

fn poolUndefine(name: string)

Undefine a storage pool (remove persistent config)

Argument	Type	Required	Description
name	string	yes	Pool name

fn poolAutostart(name: string, enabled: boolean)

Enable or disable autostart for a storage pool

Argument	Type	Required	Description
name	string	yes	Pool name
enabled	boolean	yes	true to enable, false to disable

fn poolRefresh(name: string)

Refresh a storage pool to discover new volumes

Argument	Type	Required	Description
name	string	yes	Pool name

fn volList(pool: string)

List all volumes in a storage pool

Argument	Type	Required	Description
pool	string	yes	Pool name

fn volGet(name: string, pool: string)

Get detailed info for a storage volume including XML

Argument	Type	Required	Description
name	string	yes	Volume name
pool	string	yes	Pool name

fn volCreate(pool: string, name: string, capacity: string, format: enum, allocation?: string)

Create a new storage volume. Idempotent: succeeds if volume already exists.

Argument	Type	Required	Description
pool	string	yes	Pool name
name	string	yes	Volume name
capacity	string	yes	Capacity with unit (e.g. 10G, 500M, 1T)
format	enum	yes	Volume format
allocation?	string	no	Initial allocation with unit (for thin provisioning, e.g. 0)

fn volDelete(name: string, pool: string)

Delete a storage volume

Argument	Type	Required	Description
name	string	yes	Volume name
pool	string	yes	Pool name

fn volResize(name: string, pool: string, capacity: string, shrink: boolean)

Resize a storage volume

Argument	Type	Required	Description
name	string	yes	Volume name
pool	string	yes	Pool name
capacity	string	yes	New capacity with unit (e.g. 20G)
shrink	boolean	yes	Allow shrinking (data loss risk)

fn volClone(name: string, pool: string, newName: string)

Clone a storage volume

Argument	Type	Required	Description
name	string	yes	Source volume name
pool	string	yes	Pool name
newName	string	yes	New cloned volume name

Resources

pool(infinite)— Storage pool list or detail

volume(infinite)— Storage volume list or detail

actionResult(1h)— Result of a storage action

@bad-at-naming/libvirt/hostv2026.08.19.1extensions/models/libvirt_host.ts

Global Arguments

Argument	Type	Required	Description
host?	string	no	SSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode.
user	string	yes	SSH username (SSH mode only; default: root)
uri?	string	no	Libvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set.

fn info()

Get hypervisor host info (CPU, memory, versions)

fn capabilities()

Get hypervisor capabilities XML

fn sysinfo()

Get host system information (SMBIOS/DMI data)

fn cpuStats()

Get host CPU usage statistics

fn memStats()

Get host memory statistics

fn deviceList(cap?: string)

List node devices (PCI, USB, network, storage controllers, etc.)

Argument	Type	Required	Description
cap?	string	no	Filter by capability: system, pci, usb, usb_device, net, scsi_host, scsi, storage, drm

fn addRoute(destination: string, gateway: string, replace: boolean)

Add a static route on the hypervisor host (SSH host mode only; runs `ip route` over SSH)

Argument	Type	Required	Description
destination	string	yes	Destination CIDR (e.g., 10.244.0.0/16)
gateway	string	yes	Gateway IP address
replace	boolean	yes	Use 'replace' instead of 'add' to be idempotent

Resources

info(infinite)— Hypervisor host information

stats(1h)— Host statistics (CPU, memory)

devices(infinite)— Node device list

03Previous Versions3

2026.08.01.1Aug 1, 2026

2026.08.01.1 — vm.stop wait-for-shutdown guard + test-backfill to the five-suite quality standard

Fixed

@bad-at-naming/libvirt/vm stop (HIGH, data-loss): stop now waits for the domain to actually reach shut off before returning, instead of reporting state immediately after issuing virsh shutdown. A new bounded waitSeconds argument (min(0), max(3600), default 120; 0 = fire-and-forget) polls every 3s; if the domain is still not shut off when waitSeconds elapses, stop now throws instead of returning a data-losing false-success. This closes the same class of race that caused the 2026-07-13 qemu-img-live-resize incident (a dependent operation ran against a qcow2 image before the owning domain had actually released it). The fix was proven in the homelab dev copy (vm v2026.07.13.1) and is ported here adapted to this package's conn abstraction (SSH + local/URI) via getDomDetail(conn, name) — the dev copy is SSH-only and could not be copied verbatim. Tracked as the local swamp issue-lifecycle model libvirt-port-stop-wait-guard (never filed upstream as a Lab issue — @bad-at-naming/libvirt is not a @swamp/* package).
Two existing vm.stop characterization tests (libvirt_methods_test.ts, libvirt_coverage_test.ts) are flipped from mocking dominfo as "in shutdown" to "shut off", matching the new wait-then-return contract; the shutdown-verb and never-destroy assertions are unaffected. Three new wait-guard tests and one schema-boundary test are added (libvirt_methods_test.ts), using deno.land/std@0.224.0/testing/time.ts FakeTime to virtualize the 3s poll interval so the suite stays instant.
forceStop (immediate virsh destroy) is unchanged — the wait guard only applies to the graceful path.

Internal

@bad-at-naming/libvirt/network, /storage, and /host model versions are bumped to 2026.08.01.1 in lockstep with /vm and manifest.yaml (version only — no behavior change) to satisfy this repo's CI invariant that every model's embedded version matches the manifest version.

Wave-1 gap-check child of ext-quality-test-backfill, following the pihole PR #66 recipe, landed in this same release.

Added

extensions/models/libvirt_methods_test.ts — drives all 69 vm/network/ storage/host methods' success and failure/idempotent paths against a stubbed Deno.Command subprocess boundary (no real virsh/ssh call).
extensions/models/libvirt_adversarial_test.ts — hostile-input coverage: command-injection through the methods, the setUserPassword secret-leak guard, dumpxml/snapshotDumpxml log-redact-vs-store-raw pinning, and malformed-output handling.
extensions/models/libvirt_coverage_test.ts — reviewer-guard regressions on the destructive lifecycle paths (VM stop-vs-destroy, define's destroy/undefine gating, undefine's three default-false flags, snapshotDelete --children, the storage/network destroy-verb mapping, host.addRoute), each paired with a positive control.
extensions/models/libvirt_property_test.ts — fast-check-based invariants for shellQuote, buildInvocation, redactSecrets, isIdempotent, and the parseVmList/parseKV parsers, gated by FC_NUM_RUNS (deno task test:soak runs a 10000-iteration nightly soak).
quality.yaml: all five required suites now present; docs.readme and docs.changelog present, docs.skill na (no bundled Claude skill); ratchet baseline set to the measured 100% (Grade A, rubric v3).
libvirt removed from the repo-root quality-allowlist.txt in this same change.

Unchanged

The three pre-existing test files (libvirt_parse_test.ts, libvirt_connection_test.ts, libvirt_idempotency_test.ts) are byte-for-byte unchanged — they remain the contract-fixture anchor.
lib/connection.ts and lib/parse.ts runtime source is untouched.

Added 4, removed 1 models

2026.05.25.1May 25, 2026

2026.05.25.1 — idempotent network start/stop

Fixes umag/swamp-workspace#1. @bad-at-naming/libvirt/network start no longer throws when the network is already active, and stop no longer throws when it is already inactive — both mirror the VM model via virshTry + isIdempotent against new anchored networkAlreadyActive / networkNotActive IDEMPOTENT_ERRORS sets. A genuine failure (e.g. a non-existent network) still throws.

2026.05.20.1May 20, 2026

04Stats

100 / 100

Downloads

Archive size

45.2 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

Repository

https://github.com/umag/swamp-workspace

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

06Labels

#libvirt #virsh #kvm #qemu #virtualization #vm #homelab #ssh