Virtual Machines

Commands for managing the lifecycle of virtual machines — creating, starting, stopping, restarting, deleting, and inspecting running VMs.

run

Create and start a new virtual machine from a locally stored image. The daemon creates a libvirt domain based on the image spec and any provided overrides.

vmr run <NAME[:TAG]> [OPTIONS]

Arguments

Argument	Description
NAME[:TAG]	Image reference to run (e.g., myuser/my-vm:latest)

Options

Flag	Short	Description
--vm-name <NAME>	-v	Name for the VM (auto-generated from the image digest if omitted)
--cpus <COUNT>	-c	Number of virtual CPUs (overrides image default)
--memory-mb <MB>	-m	Memory in megabytes (overrides image default)
--ephemeral	-e	Use ephemeral storage — disk changes are discarded when the VM is removed
--disk-size <SIZE>	-d	Disk size for the VM (e.g., 20G, 50G)
--cloud-init <PATH>		Path to a cloud-init user-data file
--cloud-init-meta <PATH>		Path to a cloud-init meta-data file
--cloud-init-network <PATH>		Path to a cloud-init network-config file
--network <NAME>	-n	Libvirt network to attach the VM to
--activate-network		Activate the specified network if it is not already active
--publish <HOST:VM[/PROTO]>	-p	Publish a port: HOST_PORT:VM_PORT[/PROTOCOL] (e.g. 2222:22 or 8080:80/tcp)
--gpu <PCI_ADDR|NAME>		Pass through a host GPU by PCI address (0000:01:00.0) or name substring (nvidia). Repeatable. Warns if the GPU's vendor doesn't match the image's graphics label.

Examples

vmr run myuser/my-vm:latest

vmr run myuser/my-vm:latest --vm-name test-vm --cpus 4 --memory-mb 8192 --disk-size 50G

vmr run myuser/my-vm:latest -n my-network --activate-network

vmr run myuser/my-vm:latest --vm-name web -p 8080:80/tcp -p 2222:22

vmr run myuser/my-vm:latest --vm-name ml --gpu 0000:01:00.0

vmr run myuser/my-vm:latest --gpu nvidia

vmr run myuser/my-vm:latest \
  --cloud-init ./cloud-init/user-data.yaml \
  --cloud-init-meta ./cloud-init/meta-data.yaml \
  --cloud-init-network ./cloud-init/network-config.yaml

TIP

Cloud-init allows you to configure the guest OS at first boot — set hostnames, install packages, write files, configure networking, and more. Provide a standard cloud-config YAML file with the --cloud-init flag.

Even without any --cloud-init* flags, the daemon always attaches a NoCloud seed whose meta-data sets local-hostname to the (sanitized) VM name, so cloud-init-enabled guests come up with the VM name as their hostname — the same default VMCompose services get. Explicit flags and image cloud_init.* annotations take precedence over the generated seed.

describe

Show detailed information about a single VM, including its resource configuration, disk, network interfaces, attached GPUs, and runtime state.

vmr describe <VM_NAME>

Arguments

Argument	Description
VM_NAME	Name of the VM to inspect

Examples

vmr describe test-vm

When a VM has one or more GPUs attached via PCI passthrough or as a mediated device (vGPU), a GPUs section lists each one. GPUs are read directly from the VM's libvirt domain, so they appear even when the VM was created outside the daemon (for example, by TrueNAS). See vmr gpu for the host-wide GPU inventory.

start

Start a previously stopped virtual machine. The VM must already exist as a defined libvirt domain.

vmr start <VM_NAME>

Arguments

Argument	Description
VM_NAME	Name of the VM to start

Examples

vmr start test-vm

stop

Stop a running virtual machine. By default, this performs a graceful shutdown by sending an ACPI power-off signal to the guest.

vmr stop <VM_NAME> [OPTIONS]

Arguments

Argument	Description
VM_NAME	Name of the VM to stop

Options

Flag	Short	Description
--force	-f	Force immediate shutdown (equivalent to pulling the power cord)

Examples

vmr stop test-vm

vmr stop test-vm -f

WARNING

A forced stop does not give the guest OS time to flush disk buffers or shut down services cleanly. Use --force only when a graceful shutdown is unresponsive.

restart

Restart a running virtual machine. Performs a stop followed by a start.

vmr restart <VM_NAME> [OPTIONS]

Arguments

Argument	Description
VM_NAME	Name of the VM to restart

Options

Flag	Short	Description
--force	-f	Force restart without graceful shutdown

Examples

vmr restart test-vm

vmr restart test-vm -f

edit

Change a VM's resource configuration — memory, vCPUs, attached GPUs, network, or disk size. At least one option must be provided.

vmr edit <VM_NAME> [OPTIONS]

Arguments

Argument	Description
VM_NAME	Name of the VM to edit

Options

Flag	Short	Description
--memory <MB>	-m	New memory in MB (e.g. 4096)
--vcpu <COUNT>		New vCPU count
--gpu <PCI_ADDR|NAME>		Attach a host GPU, replacing the VM's current GPU set. PCI address (0000:01:00.0) or name substring (nvidia). Repeatable. Applied on the VM's next boot.
--network <NETWORK>		Reassign the VM's NIC(s) to this libvirt network. Applied on the VM's next boot.
--disk <SIZE>		Grow the VM's primary disk to this size (e.g. 40G). Grow-only; the VM must be stopped.

Examples

vmr edit test-vm --memory 4096

vmr edit test-vm --vcpu 4

vmr edit test-vm -m 8192 --vcpu 8

# Replace the VM's GPUs (repeat --gpu for more than one)
vmr edit test-vm --gpu 0000:01:00.0

# Move the VM onto a different network
vmr edit test-vm --network lab-net

# Grow the disk (VM must be stopped)
vmr edit test-vm --disk 40G

TIP

--gpu, --network, and --disk take effect on the VM's next boot, so restart the VM after editing. --disk is grow-only and requires the VM to be stopped. Pass --gpu once per GPU; the full set you pass replaces whatever GPUs the VM had. List host GPUs with vmr gpu ls.

delete

Delete one or more virtual machines. This destroys the libvirt domain and removes associated runtime state (cloud-init ISOs, ephemeral disks, etc.).

vmr delete <VM_NAME>... [OPTIONS]

Arguments

Argument	Description
VM_NAME	One or more VM names to delete

Options

Flag	Short	Description
--force	-f	Force deletion without confirmation

Examples

vmr delete test-vm

vmr delete vm-1 vm-2 vm-3 -f

WARNING

Deleting a running VM will force-stop it first. This operation is irreversible — the domain definition and all associated runtime state are permanently removed.

snapshot

Manage point-in-time snapshots of a VM's disk state. Snapshots capture the VM at a moment in time so you can roll back later.

vmr snapshot <COMMAND>

Subcommands

Subcommand	Description
create <VM_NAME> <SNAPSHOT_NAME>	Create a point-in-time snapshot
ls [VM_NAME]	List snapshots for a VM (or all VMs)
restore <VM_NAME> <SNAPSHOT_NAME>	Restore a VM to a snapshot
delete <VM_NAME> <SNAPSHOT_NAME>	Delete a snapshot

Options

Command	Flag	Short	Description
snapshot create	--description <TEXT>	-d	Optional description for the snapshot
snapshot ls	--all	-A	Show snapshots for all VMs
snapshot ls	--names-only	-q	Print only snapshot names, one per line

Examples

vmr snapshot create test-vm before-upgrade -d "Pre-upgrade checkpoint"

vmr snapshot ls test-vm

vmr snapshot ls -A

vmr snapshot restore test-vm before-upgrade

vmr snapshot delete test-vm before-upgrade

commit

Package a stopped VM's current disk state as a new local image. Optionally store the result as an overlay delta on top of a base image instead of a standalone image.

vmr commit <VM_NAME> <NAME[:TAG]> [OPTIONS]

Arguments

Argument	Description
VM_NAME	Name of the (stopped) VM to commit
NAME[:TAG]	New image reference (e.g. ubuntu/noble-custom:latest)

Options

Flag	Short	Description
--base <NAME[:TAG]>	-b	Base image to store the result as an overlay delta against

Examples

vmr commit test-vm ubuntu/noble-custom:latest

vmr commit test-vm ubuntu/noble-custom:patched --base ubuntu/noble-minimal:latest

TIP

The VM must be stopped before committing so its disk state is consistent. Use --base to keep the image small by storing only the delta from a base image — see overlays.

console

Connect to the serial console of a running VM. This attaches your terminal to the VM's serial port for direct text-based access.

vmr console <VM_NAME>

Arguments

Argument	Description
VM_NAME	Name of the VM to connect to

Examples

vmr console test-vm

ps

List running VMs with detailed process information including image name, uptime, and optionally network details.

vmr ps [OPTIONS]

Options

Flag	Short	Description
--all	-a	Show all VMs, including stopped ones
--networks	-n	Show network information for each VM
--short	-s	Compact view (STATE, NAME, vCPU, MEM, DISK, UPTIME)

Output Columns

The columns shown depend on the selected view:

View	Columns
Default	STATE, NAME, vCPU, MEM, IMAGE, DISK, IP, UPTIME
--networks / -n	STATE, NAME, vCPU, MEM, NETWORKS, UPTIME
--short / -s	STATE, NAME, vCPU, MEM, DISK, UPTIME

The output ends with a summary footer, e.g. 4 machines · 4 running.

Examples

vmr ps

vmr ps -a

vmr ps -a -n

vmr ps -s

ls

List all virtual machines known to the daemon, showing basic information regardless of their current state.

vmr ls [OPTIONS]

Options

Flag	Short	Description
--names-only	-q	Print only VM names, one per line (useful for scripting)

Output Columns

Column	Description
NAME	VM name
STATE	Current state (running or stopped)
MEM	Allocated memory (e.g. 8 GB, 512 MB)
vCPU	Number of virtual CPUs
DISK	Size of the VM's disk

The output ends with a summary footer, e.g. 9 machines · 4 running · 5 stopped.

Examples

vmr ls

vmr ls -q