Bootc - bootc-based VM Management

Overview

The bootc command manages bootable container VMs using bcvk (bootc virtualization kit). It converts OCI container images into bootable VMs for testing.

Key Concept: Unlike traditional VMs, bootc VMs are created directly from container images. This enables testing bootable containers without building disk images first.

Quick Reference

| Action | Command | Description | |--------|---------|-------------| | Add | ujust bootc add [NAME] | Create persistent VM with disk | | Delete | ujust bootc delete [NAME] | Delete VM and its disk | | Export | ujust bootc export [IMAGE] [FORMAT] | Export container as qcow2/raw image | | Images | ujust bootc images | List available bootc images | | List | ujust bootc list | List all bootc VMs | | Prereqs | ujust bootc prereqs | Verify bcvk and dependencies installed | | SSH | ujust bootc ssh [NAME] | SSH connection to VM | | Start | ujust bootc start [NAME] | Start persistent VM | | Status | ujust bootc status [NAME] | Show VM status and info | | Stop | ujust bootc stop [NAME] | Stop running VM |

Prerequisites

# Install bcvk
ujust install bcvk

# Verify installation
bcvk --version

Parameters

| Parameter | Long Flag | Short | Default | Description | |-----------|-----------|-------|---------|-------------| | action | (positional) | - | required | Action: add, list, status, ssh, etc. | | vm_name | (positional) | - | bazzite-bootc | VM name | | image | --image | -i | (varies) | Container image to boot | | cpus | --cpus | - | 2 | Number of CPUs | | ram | --ram | - | 4096 | Memory in MB | | disk_size | --disk-size | - | 20G | Disk size | | format | --format | -f | qcow2 | Export format (qcow2, raw) | | ssh_port | --ssh-port | - | 2222 | SSH port | | ssh_user | --ssh-user | - | root | SSH user |

Ephemeral Testing

Quick test that auto-deletes VM on exit:

# Test default bazzite-ai image
ujust test bootc

# Test specific image (long form)
ujust test bootc --image=ghcr.io/org/image:tag

# Test specific image (short form)
ujust test bootc -i ghcr.io/org/image:tag

# Test with more resources
ujust test bootc --image=myimage --cpus=4 --ram=8192

# Short form
ujust test bootc -i myimage --cpus=4 --ram=8192

Ephemeral mode:

Creates temporary VM
Boots to console
VM deleted when console exits

Persistent VMs

Create VMs that persist across sessions:

# Create VM with default image
ujust bootc add dev

# Create with specific image (long form)
ujust bootc add testing --image=ghcr.io/org/image:testing

# Create with specific image (short form)
ujust bootc add testing -i ghcr.io/org/image:testing

# Custom resources
ujust bootc add heavy --cpus=8 --ram=16384 --disk-size=100G

Manage Persistent VMs

# Start VM
ujust bootc start dev

# Stop VM
ujust bootc stop dev

# Delete VM
ujust bootc delete dev

Connecting to VMs

SSH Connection

# Connect to VM
ujust bootc ssh dev

# Run command (use -- separator)
ujust bootc ssh dev -- systemctl status

# Different user
ujust bootc ssh dev --ssh-user=admin

Default: ssh -p 2222 root@localhost

List VMs

ujust bootc list

Output:

NAME         STATE    IMAGE
dev          running  ghcr.io/org/image:latest
testing      stopped  ghcr.io/org/image:testing

Check Status

ujust bootc status dev

Export Disk Images

Convert bootable container to disk image:

# Export to QCOW2 (long form)
ujust bootc export --image=ghcr.io/org/image:tag

# Export to QCOW2 (short form)
ujust bootc export -i ghcr.io/org/image:tag

# Export to raw (long form)
ujust bootc export --image=ghcr.io/org/image:tag --format=raw

# Export to raw (short form)
ujust bootc export -i ghcr.io/org/image:tag -f raw

Supported formats:

qcow2 - QEMU disk image
raw - Raw disk image

Common Workflows

Quick Test New Image

# Test ephemeral (no cleanup needed)
ujust test bootc --image=ghcr.io/myorg/myimage:dev
# Exit console to destroy VM

# Short form
ujust test bootc -i ghcr.io/myorg/myimage:dev

Development Environment

# Create persistent VM (long form)
ujust bootc add dev --image=ghcr.io/myorg/myimage:latest

# Or short form
ujust bootc add dev -i ghcr.io/myorg/myimage:latest

# Start it
ujust bootc start dev

# SSH in
ujust bootc ssh dev

# Make changes, test...

# Stop when done
ujust bootc stop dev

Test Before Release

# Test testing branch
ujust test bootc --image=ghcr.io/myorg/myimage:testing

# If good, test stable
ujust test bootc --image=ghcr.io/myorg/myimage:stable

Create Installation Media

# Export to QCOW2 for cloud (long form)
ujust bootc export --image=ghcr.io/myorg/myimage:stable --format=qcow2

# Export to QCOW2 for cloud (short form)
ujust bootc export -i ghcr.io/myorg/myimage:stable -f qcow2

# Export to raw for disk imaging
ujust bootc export -i ghcr.io/myorg/myimage:stable -f raw

bcvk vs vm Command

| Feature | ujust bootc (bcvk) | ujust vm (libvirt) | |---------|----------------------|----------------------| | Image source | Container images | QCOW2 files | | Ephemeral mode | Yes | No | | Export formats | qcow2/raw | N/A | | SSH port | 2222 (fixed) | 4444 (configurable) | | Home sharing | No | Yes (virtiofs) | | Boot time | Faster | Slower | | Use case | Testing containers | Full VMs |

Use bootc when:

Testing bootable container images
Quick ephemeral tests
Building disk images from containers

Use vm when:

Need persistent VMs with home sharing
Need configurable ports
Need full libvirt features

Troubleshooting

bcvk Not Found

Fix:

ujust install bcvk

VM Won't Start

Check:

ujust bootc status dev
ujust bootc list

Common causes:

Image not pulled
Resource conflict
Disk full

Fix:

ujust bootc delete dev
ujust bootc add dev

SSH Connection Failed

Check:

ssh -p 2222 root@localhost

Common causes:

VM still booting
Port conflict (2222 used)
SSH not started

Fix:

# Wait for boot
sleep 30
ujust bootc ssh dev

# Or check console
ujust test bootc  # Watch boot process

Image Pull Failed

Check:

podman pull ghcr.io/org/image:tag

Common causes:

Network issue
Auth required
Image doesn't exist

Fix:

# Login to registry
podman login ghcr.io

# Pull manually
podman pull ghcr.io/org/image:tag

# Retry
ujust bootc add dev --image=ghcr.io/org/image:tag

Cross-References

Related Skills: vm (traditional VMs), install (bcvk installation)
Installation: ujust install bcvk
bcvk Docs: https://github.com/containers/bcvk

When to Use This Skill

Use when the user asks about:

"bootc VM", "bootable container", "test container as VM"
"bcvk", "bootc virtualization"
"ephemeral VM", "quick test VM"
"export to qcow2", "create ISO from container"