Skip to main content

​
SmolVM

SmolVM gives your app or AI agent a private sandbox to run code safely. You can execute shell commands, start a real browser, or let a language model drive a full desktop — all inside an isolated environment that never touches your host machine. SmolVM is available as a Python SDK and a CLI. Sandboxes spin up in under a second and clean themselves up when you are done.

​
What you can do

Run code safely

Execute shell commands or scripts in a clean sandbox instead of on your host machine

Start a browser

Launch a real Chromium session you can automate with Playwright or watch live through noVNC

Power your agents

Plug SmolVM into any agent framework — Agentor, PydanticAI, OpenAI Agents, LangChain, and more

​
Quick example

from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("echo 'Hello from the sandbox'")
    print(result.stdout.strip())
The with block handles the full lifecycle: it creates the sandbox when you enter and tears it down when you exit.

​
Where to start

What you want to doWhere to go
Run your first sandboxQuickstart
Build an agent with a sandboxed shellAI agent integration
Start a disposable browser sessionBrowser sessions
Let a model click and type on websitesComputer-use with OpenAI
Pass configuration into a sandboxEnvironment variables
Save and restore sandbox stateSnapshots

​
SDK or CLI?

Use the SDK when SmolVM is part of your application or agent loop and you need to create sandboxes from Python code. Use the CLI when you want to manage sandboxes from the terminal, start a browser session, or script local workflows: 
smolvm create                    # spin up a sandbox
smolvm ssh my-sandbox            # open a shell inside it
smolvm list                      # see all running sandboxes
smolvm stop my-sandbox           # tear it down
See the CLI reference for the full command list.

​
Start a browser from the CLI

You can launch an isolated browser session directly from the terminal. This is useful for quick testing, scripting, or handing the CDP endpoint to an external tool. 
smolvm browser start --live --json
The JSON response includes a session_id and local browser URLs. Use the session ID to manage the session: 
smolvm browser list
smolvm browser stop <session_id>
The cdp_url in the response can be passed to any Chrome DevTools Protocol client. For example, the PydanticAI agent-browser integration extracts the localhost port from that URL and hands it to agent-browser --cdp. To open the live browser view in your default browser: 
smolvm browser open <session_id>

​
How isolation works

Each sandbox runs inside its own virtual machine, completely separated from your host. On Linux, SmolVM uses Firecracker — lightweight microVMs backed by KVM hardware virtualization. On macOS it uses QEMU. Unlike containers, which share the host kernel, microVMs give every sandbox its own kernel. An escape would require a hypervisor exploit, not just a kernel vulnerability. You get the convenience of a simple Python API, but every command runs in its own isolated environment.

​
Performance

Typical 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

Quickstart

Set up SmolVM and run your first sandbox in minutes

Installation

Detailed installation instructions for Linux and macOS

AI agent integration

Plug SmolVM into PydanticAI, OpenAI Agents, LangChain, and more

API reference

Explore the complete API documentation

​
Community

Last modified on April 6, 2026