SmolVM

Disposable sandboxes for AI agents

Docs • Examples • Slack

---

SmolVM gives AI agents their own disposable computer. Each sandbox is a lightweight virtual machine that boots in seconds, runs any code or command you throw at it, and disappears when you're done — nothing touches your host.

Use cases

• Run untrusted code safely. Execute AI-generated code in an isolated sandbox instead of on your machine.
• Give agents a browser. Spin up a full browser session that agents can see and control in real time.
• Keep state across turns. Reuse the same sandbox throughout a multi-step workflow.

Quickstart

1. Install the package.

pip install smolvm

2. Run the one-time setup for your machine.

smolvm setup

Linux may prompt for sudo during setup so it can install host dependencies and configure runtime permissions.

3. Check that the runtime is ready.

smolvm doctor

Start a sandbox in Python

from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("echo 'Hello from the sandbox!'")
    print(result.stdout.strip())

The with block creates a sandbox, runs your command inside it, and tears the sandbox down automatically when the block exits.

Start a sandbox from the CLI

Create a sandbox, check that it's running, then stop it:

smolvm create --name my-sandbox
# my-sandbox  running  172.16.0.2

smolvm list
# NAME         STATUS   IP
# my-sandbox   running  172.16.0.2

smolvm stop my-sandbox

Open a shell inside a running sandbox:

smolvm ssh my-sandbox

Browser sessions

SmolVM can also start a full browser inside a sandbox. This is useful when agents need to navigate websites, fill out forms, or take screenshots.

Start a browser session with a live view you can watch in your own browser:

smolvm browser start --live
# Session:   sess_a1b2c3
# Live view: http://localhost:6080

Open the URL to watch the browser in real time. When you're done, list and stop sessions:

smolvm browser list
smolvm browser stop sess_a1b2c3

See examples/browser_session.py for the Python equivalent.

Examples

Getting started

What you'll learn	Example
Run code in a sandbox	quickstart_sandbox.py
Start a browser session	browser_session.py
Pass environment variables into a sandbox	env_injection.py

Agent framework integrations

These examples show how to wrap SmolVM as a tool for popular agent frameworks, so an AI model can run shell commands or drive a browser through your sandbox.

Framework	Example
OpenAI Agents	openai_agents_tool.py
LangChain	langchain_tool.py
PydanticAI — shell tool	pydanticai_tool.py
PydanticAI — reusable sandbox across turns	pydanticai_reusable_tool.py
PydanticAI — browser automation	pydanticai_agent_browser.py
Computer use (click and type)	computer_use_browser.py

Advanced

What it does	Example
Install and run OpenClaw inside a Debian sandbox with a 4 GB root filesystem	openclaw.py

Each script shows its own pip install ... line when it needs extra packages.

Security

SmolVM automatically trusts new sandboxes on first connection to keep setup simple. This is safe for local development, but you should not expose sandbox network ports publicly without extra controls. See SECURITY.md for the full policy and scope.

Performance

Median lifecycle timings on a standard Linux host:

Phase	Time
Create + Start	~572 ms
Ready to accept commands	~2.1 s
Command execution	~43 ms
Stop + Delete	~751 ms
Full lifecycle (boot, run, teardown)	~3.5 s

Run the benchmark yourself:

python3 scripts/benchmarks/bench_subprocess.py --vms 10 -v

Measured on AMD Ryzen 7 7800X3D (8C/16T), Ubuntu Linux. SmolVM uses Firecracker, a lightweight virtual machine manager built for running thousands of secure, fast micro-VMs.

Contributing

See CONTRIBUTING.md to get started.

License

Apache 2.0 — see LICENSE for details.

---

Built with 🧡 in London by Celesto AI