VM - QCOW2 Virtual Machine Management

Overview

The vm command manages bazzite-ai virtual machines using libvirt. VMs are created from pre-built QCOW2 images downloaded from R2 CDN, customized via cloud-init.

Key Concept: VMs run in user session (qemu:///session), not requiring root. Home directory is shared via virtiofs at /workspace in the VM.

Quick Reference

Action	Command	Description
Add	`ujust vm add [NAME]`	Add new VM with default image
Boot-log	`ujust vm boot-log [NAME]`	Get boot messages via guest agent
Create	`ujust vm create [NAME]`	Create VM from existing disk
Delete	`ujust vm delete [NAME]`	Delete VM and optionally its disk
Diag	`ujust vm diag [NAME]`	Full diagnostic (no SSH required)
Download	`ujust vm download [BRANCH]`	Download QCOW2 image
Exec	`ujust vm exec [NAME] CMD`	Execute command via guest-agent
Recreate	`ujust vm recreate [NAME]`	Recreate VM config preserving disk
Seed	`ujust vm seed [NAME]`	Regenerate cloud-init seed ISO
Serial	`ujust vm serial [NAME]`	Serial console connection
Shell-exec	`ujust vm shell-exec [NAME] CMD`	Execute shell command via guest agent
SSH	`ujust vm ssh [NAME]`	SSH connection to VM
Start	`ujust vm start [NAME]`	Start VM
Status	`ujust vm status [NAME]`	Show VM status
Stop	`ujust vm stop [NAME]`	Stop VM
Update	`ujust vm update [NAME] WHAT`	Update QCOW2 or seed
VNC	`ujust vm vnc [NAME]`	VNC graphical connection
Wait-agent	`ujust vm wait-agent [NAME]`	Wait for guest agent to be ready

Parameters

Parameter	Long Flag	Short	Default	Description
action	(positional)	-	required	Action: add, update, delete, download, etc.
vm_name	(positional)	-	`bazzite-ai`	VM name
url	`--url`	-	R2 CDN URL	QCOW2 image URL
cpus	`--cpus`	-	`4`	Number of CPUs
ram	`--ram`	-	`8192`	Memory in MB
disk_size	`--disk-size`	-	`100G`	Disk size
username	`--username`	`-u`	`$USER`	VM username
password	`--password`	-	(empty)	VM password
autologin	`--autologin`	-	`true`	Enable autologin
ssh_port	`--ssh-port`	-	`4444`	SSH port forwarding
vnc_port	`--vnc-port`	-	`5900`	VNC port
ssh_user	`--ssh-user`	-	`$USER`	SSH user for connection
share_dir	`--share-dir`	-	`$HOME`	Directory to share
branch	`--branch`	`-b`	`stable`	Image branch (stable/testing)
what	`--what`	-	-	Update target (for update action)

Add VM (Full Workflow)

# Default: bazzite-ai VM with auto-detect settings
ujust vm add

# Named VM with custom config (long form)
ujust vm add myvm --cpus=8 --ram=16384 --disk-size=200G

# Testing branch image
ujust vm add testing-vm --branch=testing

# Short form for branch
ujust vm add testing-vm -b testing

# Different SSH port
ujust vm add dev-vm --ssh-port=4445

# No home sharing
ujust vm add isolated --share-dir=''

The add command:

Downloads QCOW2 image (cached)
Creates cloud-init seed ISO
Creates libvirt VM
Configures port forwarding

Individual Steps

Download QCOW2

# Stable image (default)
ujust vm download

# Testing branch (long form)
ujust vm download --branch=testing

# Testing branch (short form)
ujust vm download -b testing

# Custom URL
ujust vm download --url=https://example.com/custom.qcow2

Create Seed ISO

# Long form
ujust vm seed myvm --username=developer --password=secret

# Short form for username
ujust vm seed myvm -u developer --password=secret

Create VM

ujust vm create myvm --cpus=4 --ram=8192

VM Lifecycle

Start VM

ujust vm start              # Default VM
ujust vm start myvm         # Named VM

Auto-adds VM if it doesn't exist.

Stop VM

ujust vm stop              # Graceful shutdown
ujust vm stop myvm         # Named VM

Delete VM

ujust vm delete myvm        # Remove VM and disk

Connecting to VM

SSH Connection

# Connect to default VM
ujust vm ssh

# Named VM
ujust vm ssh myvm

# Different user
ujust vm ssh myvm --ssh-user=root

# Run command (use -- separator)
ujust vm ssh myvm -- ls -la

Default SSH: ssh -p 4444 localhost

VNC Connection

ujust vm vnc              # Opens VNC viewer
ujust vm vnc myvm

Default VNC: Port 5900

Home Directory Sharing

By default, your home directory is shared to the VM at /workspace via virtiofs.

# Default: $HOME -> /workspace
ujust vm add

# Disable sharing
ujust vm add isolated --share-dir=''

# Share specific directory
ujust vm add project --share-dir=/path/to/project

Inside VM:

ls /workspace  # Your home directory

Image Branches

Branch	Tag	Description
`stable`	`:stable`	Production, tested
`testing`	`:testing`	Latest features

# Long form
ujust vm download --branch=stable
ujust vm download --branch=testing

# Short form
ujust vm download -b stable
ujust vm download -b testing

Storage Locations

Item	Location
Download cache	`~/.local/share/bazzite-ai/vm/cache/`
VM disks	`~/.local/share/libvirt/images/`
VM config	`~/.local/share/bazzite-ai/vm/<name>.conf`
Seed ISO	`~/.local/share/bazzite-ai/vm/<name>-seed.iso`

Common Workflows

Quick Test VM

# Add and start default VM
ujust vm add
ujust vm start
ujust vm ssh

Development Environment

# Create dev VM with more resources
ujust vm add dev --cpus=8 --ram=16384 --disk-size=200G

# Start it
ujust vm start dev

# SSH in
ujust vm ssh dev

# Your home is at /workspace

Testing Branch

# Test latest features (long form)
ujust vm add testing-vm --branch=testing

# Or short form
ujust vm add testing-vm -b testing

ujust vm start testing-vm
ujust vm ssh testing-vm

Multiple VMs

# Create VMs on different ports
ujust vm add dev1 --ssh-port=4444
ujust vm add dev2 --ssh-port=4445
ujust vm add dev3 --ssh-port=4446

# Start all (not a built-in command, use loop)
for vm in dev1 dev2 dev3; do ujust vm start $vm; done

Troubleshooting

VM Won't Start

Check:

ujust vm status myvm
virsh --connect qemu:///session list --all

Common causes:

Disk image not found
Port conflict
Virtiofs path issue

Fix:

ujust vm delete myvm
ujust vm add myvm

SSH Connection Refused

Check:

ssh -p 4444 localhost

Common causes:

VM not fully booted
Wrong SSH port
SSH not started in VM

Fix:

# Wait longer after start
sleep 30
ujust vm ssh myvm

# Check VM console via VNC
ujust vm vnc myvm

Virtiofs Not Working

Symptom: /workspace empty or not mounted

Cause: SHARE_DIR path issue (symlinks)

Fix:

# Delete and recreate with canonical path
ujust vm delete myvm
ujust vm add myvm --share-dir=$(readlink -f $HOME)

Out of Disk Space

Check:

qemu-img info ~/.local/share/libvirt/images/myvm.qcow2

Fix:

# Create new VM with larger disk
ujust vm delete myvm
ujust vm add myvm --disk-size=200G

Cross-References

Related Skills: bootc (alternative: bootc-based VMs)
Prerequisites: ujust config libvirtd enable
bcvk alternative: ujust install bcvk + ujust bootc

When to Use This Skill

Use when the user asks about:

"create VM", "add VM", "start VM"
"ssh to VM", "connect to VM"
"download qcow2", "VM image"
"VM not starting", "VM connection failed"
"share directory with VM", "virtiofs"

vmSafety 90Repository

Package Files

VM - QCOW2 Virtual Machine Management

Overview

Quick Reference

Parameters

Add VM (Full Workflow)

Individual Steps

Download QCOW2

Create Seed ISO

Create VM

VM Lifecycle

Start VM

Stop VM

Delete VM

Connecting to VM

SSH Connection

VNC Connection

Home Directory Sharing

Image Branches

Storage Locations

Common Workflows

Quick Test VM

Development Environment

Testing Branch

Multiple VMs

Troubleshooting

VM Won't Start

SSH Connection Refused

Virtiofs Not Working

Out of Disk Space

Cross-References

When to Use This Skill

Install

AI Quality Score

Metadata

Tags

vmSafety 90Repository ShareFavorite skill

Package Files

VM - QCOW2 Virtual Machine Management

Overview

Quick Reference

Parameters

Add VM (Full Workflow)

Individual Steps

Download QCOW2

Create Seed ISO

Create VM

VM Lifecycle

Start VM

Stop VM

Delete VM

Connecting to VM

SSH Connection

VNC Connection

Home Directory Sharing

Image Branches

Storage Locations

Common Workflows

Quick Test VM

Development Environment

Testing Branch

Multiple VMs

Troubleshooting

VM Won't Start

SSH Connection Refused

Virtiofs Not Working

Out of Disk Space

Cross-References

When to Use This Skill

Install

AI Quality Score

Metadata

Tags

vmSafety 90Repository