Skip to main content

​
Overview

VMConfig is a Pydantic model that defines the configuration for creating a microVM. It includes hardware specifications, filesystem paths, boot parameters, and runtime options.

​
Schema

class VMConfig(BaseModel):
    vm_id: str
    vcpu_count: int = 2
    mem_size_mib: int = 512
    kernel_path: Path
    rootfs_path: Path
    boot_args: str = "console=ttyS0 reboot=k panic=1 pci=off"
    backend: str | None = None
    disk_mode: Literal["isolated", "shared"] = "isolated"
    retain_disk_on_delete: bool = False
    env_vars: dict[str, str] = {}

​
Attributes

​
vm_id
str
required
Unique identifier for the VM. Must be lowercase alphanumeric with hyphens, matching pattern: ^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$ or ^[a-z0-9]$.If omitted, SmolVM auto-generates one in the format vm-{uuid_hex[:8]}.
​
vcpu_count
int
default:"2"
Number of virtual CPUs. Valid range: 1-32.
​
mem_size_mib
int
default:"512"
Memory size in MiB. Valid range: 128-16384.
​
kernel_path
Path
required
Path to the kernel image. Must exist and be a file.
​
rootfs_path
Path
required
Path to the root filesystem image. Must exist and be a file.
​
boot_args
str
default:"console=ttyS0 reboot=k panic=1 pci=off"
Kernel boot arguments. For SSH-capable VMs, include init=/init.
​
backend
str | None
default:"None"
Optional runtime backend override: "firecracker" or "qemu". If omitted, uses the manager’s default backend.
​
disk_mode
Literal['isolated', 'shared']
default:"isolated"
Disk lifecycle mode:
  • "isolated" (default): clone rootfs_path per VM for sandbox isolation
  • "shared": boot directly from rootfs_path (changes persist to source image)
​
retain_disk_on_delete
bool
default:"False"
Keep isolated VM disk after delete, so a later create with the same VM ID can reuse prior 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 pattern ^[A-Za-z_][A-Za-z0-9_]*$).Requires an SSH-capable image with init=/init in boot_args.

​
Validation

​
Path Validation

Both kernel_path and rootfs_path are validated at creation time:
  • Path must exist on the filesystem
  • Path must be a file (not a directory)
Example Error
config = VMConfig(
    kernel_path=Path("/nonexistent/kernel"),
    rootfs_path=Path("/valid/rootfs.ext4"),
)
# Raises: ValueError: Path does not exist: /nonexistent/kernel

​
VM ID Validation

The vm_id must match the pattern for valid identifiers:
  • Lowercase letters, numbers, and hyphens only
  • Must start and end with alphanumeric character
  • 1-64 characters in length
Valid Examples
VMConfig(vm_id="my-vm", ...)           # ✓
VMConfig(vm_id="vm-123", ...)          # ✓
VMConfig(vm_id="a", ...)               # ✓
Invalid Examples
VMConfig(vm_id="My-VM", ...)           # ✗ uppercase
VMConfig(vm_id="-vm", ...)             # ✗ starts with hyphen
VMConfig(vm_id="vm_123", ...)          # ✗ underscore not allowed

​
Environment Variable Validation

Environment variable keys are validated as shell identifiers:
  • Must start with letter or underscore
  • Can contain letters, numbers, and underscores
  • Case-sensitive
Example
config = VMConfig(
    vm_id="test",
    kernel_path=Path("/kernel"),
    rootfs_path=Path("/rootfs.ext4"),
    env_vars={
        "API_KEY": "secret123",      # ✓ valid
        "_DEBUG": "1",                # ✓ valid
        "PATH": "/usr/bin",           # ✓ valid
        "123_VAR": "value",           # ✗ starts with number
    },
)
# Raises: ValueError for invalid key

​
Examples

from smolvm.types import VMConfig
from pathlib import Path

config = VMConfig(
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
)
# Auto-generated vm_id, 2 vCPUs, 512 MiB RAM, isolated disk

​
Immutability

VMConfig is frozen (immutable) after creation. To modify a config, use model_copy() with updates: 
original = VMConfig(
    kernel_path=Path("/kernel"),
    rootfs_path=Path("/rootfs.ext4"),
)

# Create a modified copy
modified = original.model_copy(update={"vcpu_count": 4, "mem_size_mib": 1024})

​
Type Annotations

For type checking with mypy or similar tools: 
from smolvm.types import VMConfig
from pathlib import Path

def create_test_vm(kernel: Path, rootfs: Path) -> VMConfig:
    return VMConfig(
        vm_id="test",
        kernel_path=kernel,
        rootfs_path=rootfs,
    )

Build docs developers (and LLMs) love

Get started for freeTalk to us