Skip to main content
SmolVM is a lightning-fast, secure microVM runtime designed for high-density isolation. It provides AI agents and tools with a safe, hardware-virtualized environment to execute untrusted code without risking the host system.

​
What is SmolVM?

SmolVM is built on top of Firecracker microVMs and provides a high-level Python SDK for managing VM lifecycles, networking, and command execution. It’s specifically designed to provide a secure “sandbox” for AI agents to execute code, browse the web, or perform system-level tasks safely.

​
Why MicroVMs?

AI agents often need to execute arbitrary code (Python, JS, shell scripts) generated by LLMs. Running this code directly on your host or in standard containers can be risky.

​
MicroVM-based Security

Unlike containers that share the host kernel, SmolVM uses KVM-backed microVMs. This provides:
  • Stronger Isolation: Hardware-level virtualization creates a significantly smaller attack surface compared to containers
  • Hardware Boundaries: Each VM runs with its own kernel, making it significantly harder for malicious code to escape to the host
  • Minimal Overhead: MicroVMs boot in sub-second time with minimal resource overhead

​
Agent-First Design

SmolVM abstracts away the complexity of microVM networking, storage, and TAP devices into a simple, pythonic API designed specifically for agent workflows.

​
Architecture Components

SmolVM’s architecture consists of several key components:

​
Core SDK (smolvm.vm.SmolVM)

The core orchestrator that manages:
  • VM lifecycle (create, start, stop, delete)
  • State management via SQLite
  • Firecracker process management
  • Network configuration

​
User Facade (smolvm.facade.VM)

The high-level, user-facing class that provides:
  • Simple context manager support
  • Auto-configuration for quick setup
  • Reconnection to existing VMs

​
Network Layer (smolvm.network)

Manages Linux networking primitives:
  • TAP device creation and configuration
  • NAT rules via nftables
  • Port forwarding (both SSH and application ports)
  • IP address allocation

​
Storage Layer (smolvm.storage)

SQLite-backed state persistence:
  • VM configuration and metadata
  • Network assignments
  • Process tracking
  • Default location: ~/.local/state/smolvm/smolvm.db

​
API Client (smolvm.api)

Low-level client for Firecracker’s Unix socket API:
  • Machine configuration
  • Boot management
  • Network interface attachment

​
Host Manager (smolvm.host)

Environment validation and setup:
  • KVM support detection
  • Firecracker binary management
  • Prerequisites checking

​
VM Lifecycle

A typical SmolVM lifecycle follows this pattern: 
from smolvm import SmolVM

# 1. Create VM instance
vm = SmolVM()

# 2. Start the VM (configures networking, boots kernel)
vm.start()

# 3. Execute commands via SSH
result = vm.run("echo 'Hello from SmolVM'")
print(result.output)

# 4. Stop and cleanup
vm.stop()

​
Using Context Manager

For automatic cleanup: 
from smolvm import SmolVM

with SmolVM(mem_size_mib=2048) as vm:
    result = vm.run("free -m")
    print(result.output)
# VM automatically stopped and cleaned up

​
Performance Characteristics

SmolVM is optimized for low-latency agent workflows. Latest lifecycle timings (p50) on a standard Linux host:
PhaseTime
Create + Start~572ms
SSH ready~2.1s
Command execution~43ms
Stop + Delete~751ms
Full lifecycle (boot → run → teardown)~3.5s
Performance measured on AMD Ryzen 7 7800X3D (8C/16T), Ubuntu Linux, KVM/Firecracker backend.

​
Resource Management

​
Memory and CPU

Each VM can be configured with:
  • vCPUs: 1-32 virtual CPUs (default: 2)
  • Memory: 128-16384 MiB (default: 512 MiB)
vm = SmolVM(vcpu_count=4, mem_size_mib=2048)

​
Disk Isolation

SmolVM defaults to isolated per-VM disks (disk_mode="isolated"), so each VM gets its own writable rootfs clone (sandbox-by-default). 
from smolvm import VMConfig

# Isolated disk (default)
config = VMConfig(disk_mode="isolated")

# Shared disk across VMs
config = VMConfig(disk_mode="shared")

​
Networking

Each VM receives:
  • Dedicated TAP device
  • Private IP in 172.16.0.0/16 range
  • Automatic NAT for outbound connectivity
  • Isolated from other VMs

​
State Persistence

All VM state is stored in SQLite by default at: 
~/.local/state/smolvm/smolvm.db
This allows you to:
  • Reconnect to running VMs
  • Track resource allocation
  • Persist VM configurations
# Reconnect to an existing VM
vm = SmolVM.from_id("vm-abcdef12")
print(f"Status: {vm.status}")

​
Integration with AI Agents

​
Tool/Function Calling

Wrap SmolVM as a tool for your AI agent: 
def execute_code_in_sandbox(code: str) -> str:
    """Tool for the agent to run shell code safely."""
    from smolvm import VM
    with VM() as vm:
        result = vm.run(code)
        return result.stdout if result.exit_code == 0 else result.stderr

​
Long-running Agent Environments

For agents that need to maintain state across multiple turns: 
from smolvm import VM

# Create VM with specific ID
vm = VM(vm_id="agent-workspace")
vm.start()

# Perform actions across multiple agent turns
vm.run("pip install numpy")
vm.run("python analyze_data.py")

# Reconnect later
vm = VM.from_id("agent-workspace")

​
Next Steps

Last modified on March 3, 2026