Skip to content

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

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"