BootImage and boot helpers

Use BootImage to tell SmolVM which disk image to boot and how to boot it. It is a description only: SmolVM creates the VM, networking, and per-VM disk later when you pass the image to SmolVM.from_image().

BootImage

from pathlib import Path

from smolvm import BootImage, DirectKernelBoot

image = BootImage(
    name="alpine-tools",
    rootfs_path=Path("/var/images/alpine-tools.ext4"),
    rootfs_format="raw-ext4",
    boot=DirectKernelBoot(root="/dev/vda", init="/init"),
    backend="qemu",
    arch="amd64",
)

str

required

Human-readable image name. Blank names are rejected.

Path

required

Path to the root filesystem disk image. The file must exist.

Literal["raw-ext4", "qcow2"]

required

Disk image format. Use "raw-ext4" for raw ext4 filesystems and "qcow2" for QEMU qcow2 disks.

Path | None

default:"None"

Kernel image path for direct-kernel boot. Direct-kernel images may omit this; SmolVM.from_image(...) resolves SmolVM’s cached base kernel for the selected backend.

Path | None

default:"None"

Optional initrd image path for direct-kernel boot.

DirectKernelBoot | FirmwareBoot | None

default:"None"

Boot helper. Use DirectKernelBoot for Linux images loaded with -kernel, or FirmwareBoot for QEMU images that boot through firmware.

str | None

default:"None"

Explicit kernel command line for direct-kernel images. Mutually exclusive with boot.

Literal["firecracker", "qemu", "libkrun"] | None

default:"None"

Backend this image is built for. Public docs focus on Firecracker and QEMU; libkrun is accepted by the source but is less documented.

Literal["amd64", "arm64"] | None

default:"None"

Guest CPU architecture. Leave unset when SmolVM.from_image(...) should use the host architecture.

bool

default:"False"

Whether the image starts SSH and accepts the credentials you pass to SmolVM. Set this to True only when command helpers such as vm.run(...) can connect.

Validation rules

BootImage validates the boot contract before you launch:

Artifact paths must exist and point to files.
Direct-kernel images need either boot or boot_args.
boot and boot_args are mutually exclusive.
Firmware images must use backend="qemu" when a backend is set.
Firmware images must not set kernel_path, initrd_path, or boot_args.

Properties and methods

Literal["direct_kernel", "firmware"]

VM boot mode inferred from the boot helper.

print(image.boot_mode)
print(image.render_boot_args(backend="qemu", arch="amd64"))

method

Returns the kernel command line for direct-kernel images. Firmware images return an empty string because their boot arguments live inside the disk image.

DirectKernelBoot

Use DirectKernelBoot when SmolVM should load a Linux kernel directly.

from smolvm import DirectKernelBoot

boot = DirectKernelBoot(
    root="/dev/vda",
    init="/init",
    quiet=False,
    extra_args=("acpi=off",),
)

print(boot.render(backend="qemu", arch="host"))

str

default:"/dev/vda"

Root device passed to the kernel.

str | None

default:"/init"

Init program path. Set None when the image should use its default init.

bool

default:"True"

Mount the root filesystem read-write. When False, renders ro.

Literal["serial", "none"]

default:"serial"

Serial console setting. QEMU on arm64 uses ttyAMA0; other documented paths use ttyS0.

int

default:"1"

Kernel panic reboot delay.

str

default:"k"

Kernel reboot mode.

bool

default:"True"

Add SmolVM’s safe boot defaults such as tsc=reliable and no_timer_check.

bool | None

default:"None"

Controls the quiet boot flag. Leave unset for the default behavior, or set SMOLVM_VERBOSE_BOOT=1 to drop quiet while debugging.

tuple[str, ...]

default:"()"

Extra kernel arguments. Each entry must be one token with no spaces.

FirmwareBoot

Use FirmwareBoot for QEMU images that already contain their own bootloader, such as cloud images or Windows qcow2 disks.

from pathlib import Path

from smolvm import BootImage, FirmwareBoot

image = BootImage(
    name="ubuntu-cloud",
    rootfs_path=Path("/var/images/ubuntu.qcow2"),
    rootfs_format="qcow2",
    boot=FirmwareBoot(),
    backend="qemu",
)

Firmware images boot through QEMU firmware. They do not use kernel_path, initrd_path, or boot_args.

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

BootImage and boot helpers

BootImage

Validation rules

Properties and methods

DirectKernelBoot

FirmwareBoot

​BootImage

​Validation rules

​Properties and methods

​DirectKernelBoot

​FirmwareBoot

BootImage

Validation rules

Properties and methods

DirectKernelBoot

FirmwareBoot