VMConfig Python reference

Overview

VMConfig is a Pydantic model that defines the configuration for creating a microVM. It specifies CPU, memory, kernel, rootfs, and other runtime settings.

Model Definition

class VMConfig(BaseModel)

All VMConfig instances are immutable (frozen) after creation.

Fields

vm_id

str

default:"auto-generated"

Unique identifier for the VM. Must be lowercase alphanumeric with hyphens or underscores, matching the pattern ^[a-z0-9][a-z0-9_-]{0,62}[a-z0-9]$ or a single character ^[a-z0-9]$.If omitted or explicitly set to None, SmolVM auto-generates an ID in the format vm-<8-char-hex> (for example, vm-a1b2c3d4).

vcpu_count

int

default:"2"

Number of virtual CPUs. Valid range: 1-32.

memory

int

default:"512"

Memory size in MiB (mebibytes). Valid range: 128-16384.

guest_os

GuestOS

default:"GuestOS.ALPINE"

The operating system running inside the VM. Used by SmolVM to pick the right QEMU machine type, firmware, and device topology.Valid values:

GuestOS.ALPINE — Alpine Linux (default).
GuestOS.UBUNTU — Ubuntu Linux.
GuestOS.WINDOWS — Windows 11. Requires boot_mode="firmware" and backend="qemu", and only runs on Linux hosts. See Windows guests.

boot_mode

Literal['direct_kernel', 'firmware']

default:"direct_kernel"

How the VM boots:

"direct_kernel" — Boot a Linux kernel directly. Requires kernel_path. Used by every Linux sandbox.
"firmware" — Boot through UEFI firmware reading the disk’s own boot manager. Required for Windows guests. kernel_path must be None.

kernel_path

Path | None

required

Path to the kernel image file. The path must exist and point to a valid file. Set to None (and omitted) when boot_mode="firmware".

rootfs_path

Path

required

Path to the root filesystem image. The path must exist and point to a valid file.

rootfs_format

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

default:"None"

Declared format of rootfs_path. New configs should set this explicitly:

"raw-ext4" — a raw ext4 filesystem image (the default for ImageBuilder and DockerRootfsBuilder).
"qcow2" — a QEMU qcow2 disk image (used by Ubuntu and Windows cloud images).

When omitted, SmolVM falls back to the filename suffix (.qcow2 ⇒ qcow2, anything else ⇒ raw-ext4). Setting this correctly matters because SmolVM uses it to pick the right QEMU drive format, backing-file format, and disk-resize strategy.

boot_args

str

default:"console=ttyS0 reboot=k panic=1 pci=off"

Kernel boot arguments. For SSH-capable VMs built with ImageBuilder, include init=/init.

backend

str | None

default:"None"

Runtime backend override. Valid options:

"firecracker": Use Firecracker VMM
"qemu": Use QEMU
"libkrun": Accepted by the source API, with limited public documentation
None or "auto": Auto-detect based on host capabilities

SmolVM’s public guides focus on Firecracker and QEMU because they have the broadest current support.

qemu_network

Literal['slirp', 'tap']

default:"slirp"

How the QEMU backend connects the guest to the network. Ignored when backend="firecracker" (Firecracker always uses a host TAP device).

"slirp" — Userspace NAT with host port forwards. Works without root or host network setup, which makes it the right choice for local macOS development. This is the default.
"tap" — Attach the guest to a host TAP device on Linux, so the sandbox gets a real routable IP and falls under the same nftables NAT and isolation rules as Firecracker (egress masquerade, cross-sandbox drop, and IMDS block). Use this for multi-tenant or production Linux hosts where you need the same network isolation guarantees as Firecracker. Requires the same Linux network setup as Firecracker (ip, nft, sudo) — see network configuration.

disk_mode

Literal['isolated', 'shared']

default:"isolated"

Disk lifecycle mode:

"isolated": Clone rootfs per VM for sandbox isolation. Each VM gets its own copy.
"shared": Boot directly from rootfs_path. Multiple VMs can share the same disk image.

disk_size_mib

int | None

default:"None"

Target size in MiB for the per-VM disk. SmolVM only grows the disk — pick a value at least as large as the current rootfs size, otherwise creation fails with a clear error. Requires disk_mode="isolated"; shared base images are never resized. Works for both raw-ext4 and qcow2 rootfs formats.

grow_filesystem

bool

default:"False"

Grow the guest filesystem to fill the resized disk during VM creation. Only supported for rootfs_format="raw-ext4" images and requires e2fsprogs (e2fsck, resize2fs) on the host. For qcow2 images, leave this False and grow the partition or filesystem from inside the guest instead.

retain_disk_on_delete

bool

default:"False"

Whether to keep the isolated VM disk after deletion. When True, a later create operation with the same VM ID can reuse prior disk state.Only applies when disk_mode="isolated".

env_vars

dict[str, str]

default:"{}"

Environment variables to inject into the guest after boot via SSH. Keys must be valid shell identifiers (matching ^[a-zA-Z_][a-zA-Z0-9_]*$).Variables are persisted in /etc/profile.d/smolvm_env.sh and affect new SSH sessions/login shells.Requires an SSH-capable image (boot args must contain init=/init).

network_rate_limit_mbps

int | None

default:"None"

Optional network bandwidth limit in megabits per second. When set, SmolVM caps the guest’s outbound traffic to this rate. Must be at least 1.

port_forwards

list[PortForwardConfig]

default:"[]"

Host-to-guest TCP port forwards configured at VM launch. Each entry maps a host_port to a guest_port. Host and guest ports must be unique within the list.

from smolvm.types import PortForwardConfig

port_forwards=[
    PortForwardConfig(host_port=8080, guest_port=80),
    PortForwardConfig(host_port=3000, guest_port=3000),
]

extra_drives

list[Path]

default:"[]"

Additional block-device image paths to attach at boot. Each path must exist and point to a valid file.

Validation Rules

Path Validation

Both kernel_path and rootfs_path are validated to ensure:

The path exists on the filesystem
The path points to a file (not a directory)

Validation occurs during model instantiation.

Environment Variable Validation

All keys in env_vars must be valid shell identifiers:

Start with a letter or underscore
Contain only letters, numbers, and underscores
Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$

Invalid keys raise a ValidationError during model instantiation.

VM ID Validation

The vm_id must:

Be lowercase
Start and end with alphanumeric characters
Contain only lowercase letters, numbers, hyphens, and underscores
Be 1-64 characters long

Usage Examples

Basic Configuration

from smolvm import VMConfig
from pathlib import Path

config = VMConfig(
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
)

print(config.vm_id)  # Auto-generated, e.g., "vm-a1b2c3d4"
print(config.vcpu_count)  # 2 (default)
print(config.memory)  # 512 (default)

Custom VM ID and Resources

from smolvm import VMConfig
from pathlib import Path

config = VMConfig(
    vm_id="my-custom-vm",
    vcpu_count=4,
    memory=2048,
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
)

SSH-Capable VM with Environment Variables

from smolvm import VMConfig, SSH_BOOT_ARGS
from pathlib import Path

config = VMConfig(
    vm_id="api-server",
    vcpu_count=2,
    memory=1024,
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/alpine-ssh.ext4"),
    boot_args=SSH_BOOT_ARGS,  # Includes init=/init for SSH support
    env_vars={
        "API_KEY": "secret-key",
        "DATABASE_URL": "postgresql://localhost/mydb",
        "LOG_LEVEL": "debug",
    },
)

Shared Disk Mode

from smolvm import VMConfig
from pathlib import Path

# Multiple VMs can boot from the same rootfs
config = VMConfig(
    vm_id="shared-vm-1",
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/shared/rootfs.ext4"),
    disk_mode="shared",
)

Persistent Isolated Disk

from smolvm import VMConfig
from pathlib import Path

# Keep VM disk after deletion for state persistence
config = VMConfig(
    vm_id="stateful-vm",
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
    disk_mode="isolated",
    retain_disk_on_delete=True,
)

# Later, create a new VM with the same ID to reuse the disk
config2 = VMConfig(
    vm_id="stateful-vm",  # Same ID
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
    disk_mode="isolated",
)

Windows guest

Boot a pre-installed Windows 11 image. Requires boot_mode="firmware" and the QEMU backend; SmolVM enforces both invariants.

from smolvm import VMConfig
from smolvm.types import GuestOS
from pathlib import Path

config = VMConfig(
    vm_id="win11-vm",
    vcpu_count=4,
    memory=4096,
    guest_os=GuestOS.WINDOWS,
    boot_mode="firmware",
    kernel_path=None,
    rootfs_path=Path("/var/lib/vms/win11.qcow2"),
    rootfs_format="qcow2",
    backend="qemu",
    disk_mode="isolated",
)

For the high-level path, use SmolVM(os="windows", image=...). SmolVM handles the QEMU firmware settings and per-VM qcow2 disk setup for you.

QEMU Backend

from smolvm import VMConfig
from pathlib import Path

config = VMConfig(
    vm_id="qemu-vm",
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
    backend="qemu",
    boot_args="console=ttyAMA0 reboot=k panic=1 init=/init",
)

Immutability

VMConfig instances are frozen and cannot be modified after creation:

config = VMConfig(
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
)

# This raises an error
config.vcpu_count = 4  # ValidationError: "VMConfig" is frozen

# Instead, create a new instance
from pydantic import BaseModel

new_config = config.model_copy(update={"vcpu_count": 4})

Integration with SmolVM

Pass VMConfig to the SmolVM constructor:

from smolvm import SmolVM, VMConfig
from pathlib import Path

config = VMConfig(
    vm_id="my-vm",
    vcpu_count=2,
    memory=512,
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
    boot_args="console=ttyS0 reboot=k panic=1 init=/init",
)

with SmolVM(config) as vm:
    result = vm.run("echo 'Hello from configured VM'")
    print(result.stdout)

Building Images for VMConfig

Use ImageBuilder to create kernel and rootfs images:

from smolvm import VMConfig, SmolVM
from smolvm.build import ImageBuilder
from pathlib import Path

# Build an SSH-capable Alpine Linux image
builder = ImageBuilder()
public_key = Path("~/.ssh/id_rsa.pub").expanduser().read_text()

kernel, rootfs = builder.build_alpine_ssh_key(
    ssh_public_key=public_key,
    name="my-alpine",
    rootfs_size_mb=512,
)

# Use the built images in VMConfig
config = VMConfig(
    vm_id="alpine-vm",
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args="console=ttyS0 reboot=k panic=1 init=/init",
)

with SmolVM(config) as vm:
    result = vm.run("cat /etc/os-release")
    print(result.stdout)

Field Summary

Field	Type	Default	Range/Validation
`vm_id`	`str`	Auto-generated	`^[a-z0-9][a-z0-9_-]{0,62}[a-z0-9]$`
`vcpu_count`	`int`	`2`	1-32
`memory`	`int`	`512`	128-16384
`guest_os`	`GuestOS`	`GuestOS.ALPINE`	`alpine`, `ubuntu`, `windows`
`boot_mode`	`Literal`	`"direct_kernel"`	`"direct_kernel"`, `"firmware"`
`kernel_path`	`Path \| None`	Required for direct_kernel	Must exist as file
`rootfs_path`	`Path`	Required	Must exist as file
`rootfs_format`	`Literal \| None`	`None`	`"raw-ext4"`, `"qcow2"`
`extra_drives`	`list[Path]`	`[]`	Each must exist as file
`boot_args`	`str`	`"console=ttyS0 reboot=k panic=1 pci=off"`	Any string
`backend`	`str \| None`	`None`	`"firecracker"`, `"qemu"`, `"libkrun"`, `None`
`qemu_network`	`Literal`	`"slirp"`	`"slirp"`, `"tap"`
`disk_mode`	`Literal`	`"isolated"`	`"isolated"`, `"shared"`
`disk_size_mib`	`int \| None`	`None`	`>= 1` when set
`grow_filesystem`	`bool`	`False`	Requires `rootfs_format="raw-ext4"`
`retain_disk_on_delete`	`bool`	`False`	`True`, `False`
`env_vars`	`dict[str, str]`	`{}`	Keys must be valid shell identifiers
`network_rate_limit_mbps`	`int \| None`	`None`	>= 1 when set
`port_forwards`	`list[PortForwardConfig]`	`[]`	No duplicate host or guest ports

​Overview

​Model Definition

​Fields

​Validation Rules

​Path Validation

​Environment Variable Validation

​VM ID Validation

​Usage Examples

​Basic Configuration

​Custom VM ID and Resources

​SSH-Capable VM with Environment Variables

​Shared Disk Mode

​Persistent Isolated Disk

​Windows guest

​QEMU Backend

​Immutability

​Integration with SmolVM

​Building Images for VMConfig

​Field Summary

Overview

Model Definition

Fields

Validation Rules

Path Validation

Environment Variable Validation

VM ID Validation

Usage Examples

Basic Configuration

Custom VM ID and Resources

SSH-Capable VM with Environment Variables

Shared Disk Mode

Persistent Isolated Disk

Windows guest

QEMU Backend

Immutability

Integration with SmolVM

Building Images for VMConfig

Field Summary