Skip to main content

​
Overview

SmolVM provides a simple, intuitive interface for managing microVM lifecycles. You can create VMs using auto-configuration or custom settings, control their lifecycle states, and use context managers for automatic cleanup.

​
Auto-Configuration Mode

The simplest way to get started is with auto-configuration. SmolVM automatically provisions an SSH-ready Alpine Linux VM: 
from smolvm import SmolVM

# Auto-configured VM with sensible defaults
with SmolVM() as vm:
    print(f"VM ID: {vm.vm_id}")
    print(f"IP Address: {vm.get_ip()}")
    result = vm.run("uname -a")
    print(result.stdout)

​
Customizing Auto-Configuration

You can customize memory and disk size when using auto-config: 
with SmolVM(mem_size_mib=1024, disk_size_mib=1024) as vm:
    result = vm.run("free -h")
    print(result.output)
Auto-configured VMs use Alpine Linux with SSH pre-configured, allowing immediate command execution via vm.run().

​
Manual VM Creation

For advanced use cases, create VMs with custom configurations:
1

Build or locate your image

Use ImageBuilder to create custom images with SSH:
from smolvm import ImageBuilder
from smolvm.build import SSH_BOOT_ARGS

builder = ImageBuilder()
kernel, rootfs = builder.build_alpine_ssh(
    name="my-custom-image",
    ssh_password="secure-password",
    rootfs_size_mb=1024
)
2

Create VM configuration

from smolvm import VMConfig

config = VMConfig(
    vm_id="my-vm",
    vcpu_count=2,
    mem_size_mib=1024,
    kernel_path=kernel,
    rootfs_path=rootfs,
    boot_args=SSH_BOOT_ARGS,
)
3

Initialize and start the VM

from smolvm import SmolVM

vm = SmolVM(config)
vm.start()
print(f"VM running at {vm.get_ip()}")

​
VM Lifecycle Methods

​
Starting a VM

vm = SmolVM(config)
vm.start(boot_timeout=30.0)

# Check status
print(vm.status)  # VMState.RUNNING
The start() method:
  • Boots the microVM
  • Waits for the VM to be ready (up to boot_timeout seconds)
  • Injects environment variables if configured
  • Returns self for method chaining

​
Stopping a VM

vm.stop(timeout=3.0)
print(vm.status)  # VMState.STOPPED
Stopping sends a graceful shutdown signal. If the VM doesn’t stop within timeout seconds, it will be forcefully terminated.

​
Deleting a VM

vm.delete()
This permanently removes:
  • The VM process
  • Network configuration (TAP devices, forwarding rules)
  • VM state from the database
  • Isolated disk (unless retain_disk_on_delete=True)

​
Refreshing VM State

# Refresh cached information from the state store
vm.refresh()
print(vm.info)  # Updated VMInfo

​
Context Manager Pattern

The recommended pattern is using SmolVM as a context manager for automatic lifecycle management: 
with SmolVM(config) as vm:
    # VM automatically starts on context entry
    result = vm.run("hostname")
    print(result.output)
    # VM automatically stops and deletes on context exit

from smolvm import SmolVM

with SmolVM() as vm:
    print(f"VM {vm.vm_id} is ready")
    vm.run("echo 'Hello World'")
# Automatic cleanup

​
Context Manager Behavior

For VMs created by the facade instance (not reconnected), the VM automatically starts. Reconnected VMs remain in their current state.
  1. Stop: If the VM is running, it gracefully stops
  2. Delete: If the facade created the VM (owns it), it’s deleted
  3. Close: SDK resources are released
VMs reconnected via from_id() are stopped but not deleted.

​
Manual Lifecycle Management

For long-running VMs, manage lifecycle manually: 
from smolvm import SmolVM, VMConfig

vm = SmolVM(config)
try:
    vm.start()
    # Do work...
    result = vm.run("uptime")
    print(result.output)
finally:
    vm.stop()
    vm.delete()
    vm.close()
Always call vm.close() when you’re done to release SDK resources, even if you’re not deleting the VM.

​
Error Handling

from smolvm import SmolVM
from smolvm.exceptions import SmolVMError, OperationTimeoutError

try:
    with SmolVM(mem_size_mib=512) as vm:
        result = vm.run("some-command", timeout=10)
        if not result.ok:
            print(f"Command failed: {result.stderr}")
except OperationTimeoutError as e:
    print(f"Operation timed out: {e.message}")
except SmolVMError as e:
    print(f"VM error: {e}")

​
VM Properties

with SmolVM() as vm:
    # Unique identifier
    print(vm.vm_id)
    
    # Current status (VMState enum)
    print(vm.status)  # VMState.RUNNING
    
    # Full VM information
    print(vm.info)  # VMInfo object
    
    # Guest IP address
    print(vm.get_ip())
    
    # Data directory
    print(vm.data_dir)
    
    # Check if commands can be executed
    print(vm.can_run_commands())  # True for SSH-capable VMs

​
Next Steps

Command Execution

Learn how to run commands inside VMs via SSH

Environment Variables

Manage environment variables in running VMs

Reconnecting VMs

Reconnect to existing VMs for persistent workflows

Custom Images

Build custom rootfs images with ImageBuilder

Build docs developers (and LLMs) love

Get started for freeTalk to us