Skip to main content

​
SmolVM

Run code, start a browser, and give AI agents an isolated workspace. SmolVM is a Python SDK and CLI that lets you spin up a disposable sandbox in under a second. Use it whenever your app or AI agent needs a safe place to run shell commands, open a browser, or execute untrusted code — without touching your host machine.

​
What you can do

Run code safely

Execute untrusted code in a clean sandbox instead of on your host machine

Start a browser

Launch a real browser session you can automate or watch live

Power your agents

Plug SmolVM into agent frameworks for shell, browser, and computer-use workflows

​
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 on entry and tears it down on exit.

​
Use cases

What you want to doWhere to start
Run code in a clean sandboxQuickstart
Build an agent with a sandboxed shell (Agentor)Agentor integration
Start a disposable browser sessionBrowser sessions
Let a model click and type on websitesComputer-use with OpenAI
Let an agent drive a browser via CLIPydanticAI with agent-browser
Give an agent a shell toolAI agent integration
Keep one sandbox across turnsReusable sandbox
Pass env vars into the guestEnvironment variables

​
SDK or CLI?

Use the SDK when SmolVM is part of your application or agent loop and you want to create sandboxes from Python code. Use the CLI when you want to inspect the runtime, start a browser from the terminal, or script local workflows: 
smolvm create                    # auto-generates a name
smolvm create --name my-sandbox  # or pick your own
smolvm ssh my-sandbox
smolvm list
smolvm stop my-sandbox
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 the session_id plus 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 CDP 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

SmolVM runs your work inside a separate guest system instead of on your host. On Linux it uses Firecracker microVMs — very small virtual machines backed by KVM. On macOS it uses QEMU. You get a simple Python API and CLI, but every command executes in its own environment. Unlike containers that share the host kernel, microVMs provide hardware-level isolation. An escape would require a hypervisor exploit, not just a kernel vulnerability.

​
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 3, 2026