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 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 on stop (default: true)
--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

Examples

vmr run myuser/my-vm:latest

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

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

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.

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

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.

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

Output Fields

Field	Description
VM ID	Unique identifier for the VM
Name	VM name
Status	Current state (running, stopped, paused, etc.)
Image	Source image reference
Created	When the VM was created
Uptime	How long the VM has been running
Networks	Attached network names, MAC addresses, and interface types (with -n)

Examples

vmr ps

vmr ps -a

vmr ps -a -n

vms

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

vmr vms

Output Fields

Field	Description
Name	VM name
Status	Current state
Memory (MB)	Allocated memory in megabytes
vCPUs	Number of virtual CPUs
Disk Size	Size of the VM's disk

Examples

vmr vms