---

name: vm description: | QCOW2 virtual machine management using libvirt. Creates VMs from pre-built images downloaded from R2 CDN with cloud-init customization. Supports SSH, VNC, and virtiofs home directory sharing. Use when users need to create, manage, or connect to bazzite-ai VMs.

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

Parameters

Add VM (Full Workflow)

Copy# 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:

1. Downloads QCOW2 image (cached)
2. Creates cloud-init seed ISO
3. Creates libvirt VM
4. Configures port forwarding

Individual Steps

Download QCOW2

Copy# 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

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

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

Create VM

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

VM Lifecycle

Start VM

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

Auto-adds VM if it doesn't exist.

Stop VM

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

Delete VM

Copyujust vm delete myvm        # Remove VM and disk

Connecting to VM

SSH Connection

Copy# 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

Copyujust 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.

Copy# 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:

Copyls /workspace  # Your home directory

Image Branches

Copy# 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

Common Workflows

Quick Test VM

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

Development Environment

Copy# 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

Copy# 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

Copy# 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:

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

Common causes:

• Disk image not found
• Port conflict
• Virtiofs path issue

Fix:

Copyujust vm delete myvm
ujust vm add myvm

SSH Connection Refused

Check:

Copyssh -p 4444 localhost

Common causes:

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

Fix:

Copy# 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:

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

Out of Disk Space

Check:

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

Fix:

Copy# 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"