SmolVM

Secure, persistent computers that AI agents can use to browse, run code, and get real work done.

Quick start • Examples • Features • Performance • Docs • Discord

SmolVM gives AI agents their own secure and persistent computer. Each microVM boots in milliseconds, runs any code or software you throw at it, persists files and state across sessions, and disappears when you're done — ready to handle thousands of sandboxes in production.

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 sandbox 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

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 in TypeScript (alpha)

The TypeScript SDK gives Node.js agents a disposable computer on the same machine. It starts the local runtime automatically, so there is no server command or cloud credential to configure.

The alpha supports Node.js 20.4 or newer on Linux x64 and Apple Silicon macOS. After installing SmolVM above, install the preview package and tsx:

npm install https://github.com/CelestoAI/SmolVM/releases/download/typescript-v0.1.0-preview.1/celestoai-smolvm-0.1.0-preview.1.tgz
npm install --save-dev tsx

import { SmolVM } from "@celestoai/smolvm";

async function main() {
  const smolvm = new SmolVM({ onEvent: (event) => console.log(event.type) });
  const sandbox = await smolvm.sandboxes.create({ network: { mode: "off" } });

  try {
    await sandbox.files.write("/workspace/input.txt", "hello");
    const result = await sandbox.exec(
      ["sh", "-c", "tr a-z A-Z < /workspace/input.txt"],
      { timeoutMs: 30_000 },
    );
    console.log(result.stdout);
  } finally {
    await smolvm.close();
  }
}

main().catch((error) => { console.error(error); process.exitCode = 1; });

Run it with npx tsx quickstart.ts. See the TypeScript guide for files, network rules, cancellation, diagnostics, CI, and the current alpha limits.

Start a sandbox from the CLI

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

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

smolvm sandbox list
# NAME         PRESET  STATUS   PID
# my-sandbox   -       running  12345

smolvm sandbox stop my-sandbox

Open a shell inside a running sandbox:

smolvm sandbox shell my-sandbox

Use smolvm sandbox ssh my-sandbox when you specifically need an SSH session.

Run a single command in a running sandbox without opening a shell — useful in scripts. Put the command after --, and add --start if you want a stopped sandbox started first:

smolvm sandbox exec my-sandbox -- python --version

If something goes wrong, read the sandbox's logs (add --follow to watch them live):

smolvm sandbox logs my-sandbox

Tip: turn on tab completion so your shell can finish commands and sandbox names for you — run smolvm completion bash --install (or zsh, fish) once. See the CLI reference for details.

macOS desktop sandbox (preview)

On an Apple Silicon Mac, SmolVM can open a temporary macOS desktop for testing apps and installers without changing your everyday system. The first run downloads macOS from Apple and prepares a reusable local image.

smolvm setup --macos

Create the desktop sandbox:

smolvm sandbox create --os macos --name test-mac
# Next: smolvm sandbox desktop test-mac

Open it in the built-in Screen Sharing app:

smolvm sandbox desktop test-mac

Image preparation needs about 50 GB and 20–40 minutes. macOS images stay on the Mac that created them, and at most two macOS guests can run at once. See the macOS desktop guide for shared folders, limits, and cleanup.

Windows sandbox

SmolVM can boot a Windows 11 guest as well as Linux. Hand it a Windows image and you get the same Python and CLI you use for Linux — run PowerShell, upload files, set environment variables, and run many sandboxes in parallel from one baseline image.

from smolvm import SmolVM

with SmolVM(
    os="windows",
    image="~/.smolvm/images/win11.qcow2",
    ssh_user="smolvm",
    ssh_password="smolvm",
) as vm:
    print(vm.run("Write-Output 'hello from windows'").stdout)

Build your own image from a Windows ISO:

smolvm windows build-image --iso ./Win11.iso \
    --virtio-win-iso ./virtio-win.iso \
    --output ~/.smolvm/images/win11.qcow2

Windows guests need a Linux host with KVM. Host mounts, network controls, and snapshots are Linux-only today. See the full Windows guide for details.

Coding agents

It sucks to “press enter and accept changes” every few seconds while using coding agents. SmolVM makes it easy to isolate the agent coding environment from the host (laptops).

Start any supported coding agent in its own sandbox:

Video tutorial:

smolvm codex start
smolvm claude start
smolvm pi start
smolvm hermes start
smolvm opencode start
smolvm openclaw start --name openclaw-work --no-attach

OpenClaw also has a private browser dashboard. Open it after the named sandbox starts:

smolvm openclaw list
# NAME              STATUS   PID
# openclaw-work     running  12345

smolvm openclaw open-ui openclaw-work

Creating an OpenClaw sandbox currently takes several minutes while SmolVM installs its supported Node.js runtime and pinned OpenClaw release. See the OpenClaw guide for credentials, the dashboard flow, and safe steps for replacing an older sandbox.

Browser sandbox

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

Start a visible browser sandbox from Python:

from smolvm import SmolVM

with SmolVM.browser(headless=False) as browser:
    print(browser.cdp_url)  # Automation endpoint for Playwright or CDP tools
    print(browser.viewer_url)  # Web URL you can open to watch live
    print(browser.display_url)  # VNC URL for clients or computer-use agents

Use browser.cdp_url when a browser automation tool needs a Chromium DevTools connection address. Use browser.viewer_url when you want to watch the session in your own browser. Use browser.display_url when a VNC client or computer-use agent needs to control the screen.

Start the same browser sandbox from the CLI:

smolvm browser start --live
# Sandbox: browser-a1b2c3d4
# Viewer URL: http://127.0.0.1:36080/vnc.html?autoconnect=1&resize=scale  # open in a browser
# Display URL: vnc://127.0.0.1:35900                                      # give to a VNC client or agent

Use SmolVM.browser(headless=True) for browser automation only; it gives you cdp_url and no visible viewer. Use SmolVM.browser(headless=False) for a visible browser; it gives you cdp_url, viewer_url, and display_url. Use SmolVM.desktop() for a full desktop display; it gives you viewer_url and display_url, and may not provide a browser automation endpoint.

Open the viewer URL to watch the browser in real time, or give the display URL to a computer-use agent or VNC client. When you're done, list and stop sandboxes:

smolvm browser list
smolvm browser stop sess_a1b2c3

See examples/browser_sandbox.py for a complete Python example.

Network controls

Sandboxes have internet access by default. On Linux with Firecracker, turn outbound access off while keeping commands and file transfers available through a direct connection (vsock):

from smolvm import SmolVM

with SmolVM(
    backend="firecracker",
    comm_channel="vsock",
    internet_settings={"mode": "off"},
) as vm:
    print(vm.run("echo hello").stdout)

Use mode="restricted" with allowed_cidrs to allow specific IPv4 addresses or ranges. These modes require private networking and do not support shared folders or exposed ports. Command output and explicit file downloads still work when outbound access is off.

Existing allowed_domains lists allow the IP addresses found during setup; they do not verify the hostname on each connection. DNS servers are not automatically allowed.

See the networking guide for a restricted-access example and supported configurations.

Mount host directories

You can give a sandbox 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 sandbox create --name my-sandbox --mount ~/Projects/my-app
smolvm sandbox shell my-sandbox
ls /workspace   # your host files appear here

By default 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 sandbox create --mount ~/Projects/my-app:/code --mount ~/data:/mnt/data

When you do want the sandbox to edit your host files, add --writable-mounts:

smolvm sandbox create --mount ~/Projects/my-app --writable-mounts

Every directory passed with --mount becomes writable; writes from the guest are visible on the host immediately. The flag applies to all mounts on that command, so don't pair a folder you want the sandbox to modify with one you want kept untouched.

The same works from Python:

from smolvm import SmolVM

with SmolVM(mounts=["~/Projects/my-app"], writable_mounts=True) as vm:
    vm.run("echo hello > /workspace/from-sandbox.txt")

Upload a file

You can copy one file into a running sandbox without mounting a whole folder. This is useful when an agent needs a config file, script, or small input file.

# Copy a file from your machine into the sandbox.
smolvm sandbox file upload my-sandbox ./prompt.txt /tmp/prompt.txt

# Open a shell in the sandbox to confirm the file is there.
smolvm sandbox shell my-sandbox
# Then, inside the sandbox shell:
cat /tmp/prompt.txt

For a temporary, one-shot sandbox, the same works from Python. The sandbox and uploaded file are deleted when the context exits:

from smolvm import SmolVM

with SmolVM() as vm:
    vm.upload_file("./prompt.txt", "/tmp/prompt.txt")

The destination must be an absolute path inside the sandbox (starting with /), and any existing file at that path is overwritten.

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

SmolVM ships a benchmark suite that measures the timings AI agents actually feel: cold start, time-to-interactive, pause/resume, and snapshot create/restore. It drives the public Python SDK on whichever backend is native to your host — Firecracker on Linux, QEMU on macOS.

Run it locally:

uv run python scripts/benchmarks/bench.py

See scripts/benchmarks/README.md for flags, output format, and what each metric means.

Contributing

See CONTRIBUTING.md to get started.

License

Apache 2.0 — see LICENSE for details.