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

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

VMConfig Python reference

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

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