SmolVM: a persistent microVM runtime for AI agents

The gap SmolVM fills between a container and a full VM

An agent that writes and executes code needs an execution surface that is both cheap enough to create per task and strong enough that a bad generation cannot reach the host. A container is cheap but shares the kernel, so a kernel-level escape is a host compromise. A conventional VM is isolated but slow to provision and awkward to keep alive across a multi-step workflow. SmolVM positions itself in that gap: the README describes each sandbox as running in its own virtual machine with hardware-level separation, booting in roughly 500 ms so that, per the project's wording, your agent has a running VM before the API call returns. The stated audience is people building long-running agents: the description names browser agents, computer-use agents, and the OpenClaw and browser-use topics. If your agent's loop is a single tool call that formats a string, this is the wrong layer. If your agent needs to install a package, open a page, and come back to the same filesystem two turns later, the persistence guarantee is the actual product.

How a sandbox is created, persisted, and snapshotted

The Python surface is deliberately small. You import SmolVM, construct it, call run with a shell string, and call stop. The README's example is a single echo, which tells you the API is a remote-execution wrapper rather than an agent framework. The CLI exposes the same lifecycle with more visibility: sandbox create takes a name, sandbox list reports NAME, PRESET, STATUS and PID, and sandbox stop tears it down. Persistence is the differentiator the project leans on hardest. The README states that snapshots pause a sandbox and resume it later with memory, disk, and running processes intact, which is a stronger claim than filesystem-only checkpointing because it implies process state survives. File sharing is the second persistence mechanism: host directories can be mounted read-only or writable so the agent works on the real codebase instead of a copy. Network controls are described as turning outbound access off or restricting it to specific IP addresses, and the README attaches that capability specifically to Linux Firecracker, which is a scoping detail worth noticing rather than a footnote.

Installation paths and the commands you actually type

The one-line installer is curl -sSL https://celesto.ai/install.sh | bash, which the README says installs Python, configures the machine, and verifies the setup. Piping a remote script into a shell is a supply-chain decision, and the project offers a manual path for people who decline it: pip install smolvm, then smolvm setup, then smolvm doctor. On supported Linux and macOS systems the pip install also pulls a matching smolvm-core wheel, so Rust is not required for the default path. Linux may prompt for sudo so setup can install host dependencies and configure runtime permissions; that is a real privilege boundary and you should know what it touches. Day-to-day commands are smolvm sandbox create --name my-sandbox, smolvm sandbox shell my-sandbox for an interactive shell, smolvm sandbox ssh my-sandbox when you specifically need SSH, and smolvm sandbox exec my-sandbox -- python --version to run one command from a script. Add --start to exec if the sandbox is stopped. When something fails, smolvm sandbox logs my-sandbox reads the logs and --follow tails them. Tab completion is installed once with smolvm completion bash --install, or zsh or fish.

Where the isolation story gets thinner than the pitch

Hardware isolation via microVM is the right default for untrusted code, but the README's own scoping undercuts a uniform security story. Network controls are tied to Linux Firecracker, so on other backends the outbound restrictions may not apply in the same way, and the README does not spell out the fallback behaviour. The Windows 11 guest is described as Linux-host-only for now, which means the Windows sandbox is a capability you cannot use from a macOS or Windows workstation. The macOS desktop sandbox is explicitly labelled preview and, per the README, downloads macOS from Apple on first run to prepare a reusable local image, so the first boot is not the sub-second experience advertised for the Linux path. Version numbers are also worth reading literally: v0.0.33 shipped on the same day as the last push to main, and a 0.0.x line is telling you the API is not frozen. If your integration depends on snapshot semantics or on a specific preset, pin the version and expect churn.

Preinstalled coding agents and the credential question

One command launches a sandbox with Claude Code, Codex, or Pi pre-installed and git credentials forwarded, according to the README. That is convenient and it is also the highest-risk configuration in the project. Forwarding git credentials into a sandbox that an agent controls means the agent's blast radius includes whatever those credentials authorize. SmolVM gives you the tools to bound that: mount the working directory read-only rather than writable, and restrict outbound network access to specific addresses on the Firecracker path. The README does not document a credential-scoping model beyond the forwarding behaviour, so the burden of deciding what to hand over sits with you. Treat the coding-agent preset as a starting point to be narrowed, not a safe default to be adopted as-is.

How SmolVM differs from plain Docker or a hosted code-execution API

The obvious comparison is Docker with a seccomp profile. Docker starts faster and has a larger ecosystem, but it shares the host kernel, so isolation depends on the kernel's correctness rather than on a hypervisor boundary. SmolVM's answer is a microVM per sandbox with a Python client and a state model that includes snapshots of running processes. The other comparison is a hosted execution API from a cloud provider: those remove the host dependency entirely, but they typically execute a function and return, and they do not give you a persistent machine with a mounted local directory and a browser you can watch. SmolVM's trade is the inverse. You keep the sandbox on infrastructure you control and you accept the host requirements: Firecracker on Linux, sudo during setup, and a Windows guest path that only works when the host is Linux. If your workload is short-lived and stateless, the hosted option is simpler and you should take it.

Licence, maintenance, and what 0.0.x costs you

The repository is Apache-2.0, which permits commercial use and modification and includes a patent grant, but the README does not discuss trademark terms or how the project handles contributions, and this is not legal advice. Operationally, the release cadence visible in the material is fast: v0.0.31, v0.0.32, and v0.0.33 all landed within four days in September 2026, with the last push to main on the same day as v0.0.33. Fast releases on a 0.0.x line mean upgrade cost is real. Pin smolvm and smolvm-core to matching versions, because the README says the core wheel is pulled automatically to match, and read the release notes before moving. The README also points to docs/installation.md for golden-AMI builds, two-stage deploys, and pinning the Firecracker version, which is the material you will need if you run this on your own hosts rather than a developer laptop. There is no stated long-term support window, no deprecation policy, and no compatibility matrix for guest images in the supplied material.

Editorial conclusion

Adopt SmolVM if you are running untrusted, agent-generated code on a Linux host and need state to survive between turns. Do not adopt it if your fleet is Windows or your agents only need a process-level sandbox, since the Windows guest path is Linux-host-only and the macOS desktop sandbox is labelled preview. Before committing, run smolvm doctor on your target host, check whether your kernel supports the Firecracker path or whether you will fall back to Docker, and confirm the snapshot and network-control features behave as documented in your environment rather than only in the docs.

Official sources

1. CelestoAI/SmolVM on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases