shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

bootc

bootc VM management via bcvk (bootc virtualization kit). Run bootable containers as VMs for testing. Supports ephemeral (quick test) and persistent modes. Use when users need to test bootable container images as virtual machines.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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"