Skip to main content

SmolVM

Secure runtime for AI agents and tools 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.

Why SmolVM?

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 (Firecracker on Linux, QEMU on macOS). This provides a significantly smaller attack surface and stronger hardware-level isolation.
  • Agent-First Design: SmolVM abstracts away the complexity of microVM networking, storage, and TAP devices into a simple, pythonic API.
  • Sub-second Boot: MicroVMs boot in milliseconds with minimal overhead, making them perfect for ephemeral sandboxes.

Key Features

Secure Isolation

Hardware-level virtualization utilizing Firecracker for strong sandbox boundaries

Blazing Fast

MicroVMs boot in sub-second time with ~43ms command execution overhead

Python Native

Clean, high-level SDK for managing VM lifecycles and command execution

Automatic Networking

Built-in NAT, port forwarding, and SSH tunneling

Custom Images

Build specialized Debian-based rootfs images with your own tools

Auto-Cleanup

Integrated resource management to keep your host system clean

Quick Example

from smolvm import SmolVM

# Start sandboxed runtime
with SmolVM() as vm:
    # Run ANY command like a real system
    result = vm.run("echo 'Hello from the sandbox!'")
    print(result.output)

Performance

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
Measured on AMD Ryzen 7 7800X3D (8C/16T), Ubuntu Linux, KVM/Firecracker backend.

Get Started

Use Cases

AI Agent Code Execution

Provide LLM-powered agents with a safe sandbox to execute generated code:
def execute_code_in_sandbox(code: str) -> str:
    """Tool for the agent to run shell code safely."""
    from smolvm import SmolVM
    with SmolVM() as vm:
        result = vm.run(code)
        return result.stdout if result.exit_code == 0 else result.stderr

Long-running Agent Environments

Maintain state across multiple turns:
from smolvm import SmolVM

# Create a VM with a specific ID
vm = SmolVM()
vm.start()

# Perform actions across multiple turns
vm.run("pip install requests")
vm.run("python my_script.py")

# Reconnect later
vm_reconnected = SmolVM.from_id(vm.vm_id)
print(vm_reconnected.status)

Community


Built with ๐Ÿงก in London by Celesto AI
Last modified on March 3, 2026