Tutorials

Sandbox your AI agent in a branchable microVM: a hands-on guide to smolvm

Giving your coding agent a shell on your own laptop is how you get your home directory wiped by a bad command. smolvm gives that same agent its own hardware-isolated microVM — its own kernel, a locked-down network, and the ability to checkpoint, branch, and rewind mid-run like a git repo. Here is how to set one up.

MDMarcus DoyleSenior Technology Writer · 2026-10-21 · 8 min read

TL;DR: smolvm (smol-machines/smolvm, Apache-2.0, 6,700+ GitHub stars) runs each AI agent workload in its own hardware-isolated microVM — own guest kernel, sub-second boots, no Docker daemon — and lets you checkpoint, branch, and rewind a running machine like a git repo. This guide installs v1.30.1, builds a persistent agent sandbox with a network allow-list, and packs it into a single portable .smolmachine file.

What: smolvm (smol-machines/smolvm) — branchable microVMs for AI agents, Apache-2.0 licensed.
Traction: 6,700+ GitHub stars and 333 forks as of Oct 21, 2026; latest release v1.30.1 (Oct 17, 2026).
Speed: boots in under a second; the project’s own comparison table puts it under 200 ms to agent-ready.
Defaults: 4 vCPUs and 8 GiB RAM per machine, elastic via virtio balloon — the host only commits what the guest uses.
Isolation: networking is off by default; egress can be restricted to named hosts with --allow-host.
Runs on: macOS 11+ on Apple Silicon, Linux x86_64/aarch64 with KVM (/dev/kvm), Windows x86_64 with Windows Hypervisor Platform.

Every coding agent eventually asks for the same thing: a shell. Run its commands on your laptop and you are one hallucinated rm -rf ~ away from a very bad afternoon. Put it in a container and you are safer — until you remember the container shares your host kernel. That is the gap smolvm was built for: every workload gets a real virtual machine with its own guest kernel, booting in under a second, with no Docker daemon involved. And then it does the thing containers never could: checkpoint, branch, and rewind a running machine the way git branches code.

The project is smol-machines/smolvm — Apache-2.0, 6,700+ GitHub stars, actively released (v1.30.1 landed Oct 17, 2026). Under the hood it uses libkrun as the VMM and libkrunfw for the guest kernel, on Hypervisor.framework (macOS), KVM (Linux), or the Windows Hypervisor Platform. Images are plain OCI, so anything on Docker Hub boots as a microVM directly. The README even ships one documentation folder per task, each with a SKILL.md your agent can follow — this tool was designed to be driven by agents, not just humans.

What you'll need

A host smolvm supports: macOS 11+ on Apple Silicon, Linux x86_64 or aarch64 with KVM (/dev/kvm must exist), or Windows x86_64 with the Windows Hypervisor Platform enabled. macOS Intel has no published release build and is untested.
curl or wget plus tar for the installer — on Linux the installer itself checks for /dev/kvm before downloading anything.
Internet access for the install and the first image pull (we use Alpine and python:3.12-alpine).
Roughly 8 GiB of free RAM. Defaults are 4 vCPUs / 8 GiB per machine, but memory is elastic via virtio balloon, so the host only commits what the guest actually uses.

Step 1 — Install smolvm

Two official paths, straight from the README:

brew install smol-machines/tap/smolvm                  # macOS (Homebrew)
curl -sSL https://smolmachines.com/install.sh | bash   # macOS + Linux

On Windows, unzip the windows-x86_64 asset from the releases page and run smolvm.exe (it needs the Windows Hypervisor Platform). Then confirm the install — the README's advice is blunt: run smolvm --help after installing to discover every command, and it is genuinely the fastest way to learn the CLI.

Step 2 — Boot your first one-off microVM

The quickest possible run — a single command inside a fresh Alpine VM that is removed when it exits:

smolvm machine run --net --image alpine -- uname -a          # one-off VM, removed on exit

Note the --net: networking is off by default, so you opt in explicitly. The first boot pulls the Alpine OCI image; subsequent boots reuse it. Want a shell instead of a single command?

smolvm machine run --net -it --image alpine -- /bin/sh       # interactive shell

That -it shell is running on its own kernel inside a VM — not in a namespace on yours. Type exit and the machine is gone.

Step 3 — Build a persistent sandbox for your agent

One-off VMs are for experiments. For an agent you want a machine that sticks around:

smolvm machine create --net --name agent-box --image python:3.12-alpine
smolvm machine start --name agent-box
smolvm machine exec --name agent-box -- apk add git

Machines persist across restarts, and any OCI image works — including one you built locally, with no registry in the loop:

docker save myapp | smolvm machine run --image - -- ./app    # local image, no registry

This is the operational pattern: stop handing your coding agent raw host commands and hand it smolvm machine exec --name agent-box -- <cmd> instead. Everything the agent does — installing packages, cloning repos, running test suites — happens inside the VM. Your laptop never sees it.

Step 4 — Checkpoint, branch, and rewind a running machine

This is smolvm's superpower, and the reason it beats containers for agent work. Containers give you image layers; smolvm gives you live state:

smolvm machine create --net --name agent --image alpine
smolvm machine start --name agent --branchable
smolvm machine branch --from agent --name try-1                   # live copy-on-write child
smolvm machine checkpoint --name agent -o agent.checkpoint        # save it, processes and all
smolvm machine create --name agent2 --from agent.checkpoint       # resume later or elsewhere

Credit: AI Frontier Post — checkpoint, then branch: copy-on-write children of a live machine

What each piece does, per the docs:

--branchable on start enables branching for that machine.
branch forks a live, copy-on-write child that keeps running from the same point — run two agent experiments in parallel from identical state instead of serializing them.
checkpoint captures RAM, CPU state, and disks to a file. Rewind to an earlier generation with --from <checkpoint> --at '~N' (generations are listed by machine checkpoint-log).
Checkpoints are portable: restore one on another host or on smol cloud — the project documents resuming an arm64 Mac checkpoint on arm64 Linux. And pause and resume lets you stop a machine without losing execution at all.

The workflow this unlocks: checkpoint right before the risky step. If the agent wrecks the environment, you rewind in seconds instead of rebuilding for twenty minutes.

Step 5 — Lock down the network to an allow-list

Isolation is only as good as its egress policy. smolvm's default-deny model is simple: no network unless you pass --net, and then you narrow it with --allow-host. The README's own demo allows only the npm registry and proves the rest is blocked:

smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -qO- https://google.com   # blocked

Credit: AI Frontier Post — default-deny networking: nothing leaves the VM unless you allow it

The matching rules are precise: --allow-host example.com allows the apex and its subdomains, while --allow-host-pattern '*.example.com' allows subdomains only. Grants can be added or removed on a running machine with smolvm machine update (--remove-allow-host and friends).

For secrets, use credential substitution — the workload can use an API key without ever reading it:

NOTION_API_KEY=secret_… smolvm machine run --net --image alpine \
  --credential [email protected] -- sh -c 'echo $NOTION_API_KEY'   # a placeholder

One honest caveat from the security docs, worth internalizing: smolvm provides the boundary, but safety is a shared responsibility. Every folder you mount, port you open, host you allow, and secret or SSH agent you forward becomes something the workload can use — so give an untrusted workload only what it needs.

Step 6 — Pack the machine into a single portable file

When the sandbox is exactly how you want it — dependencies installed, tools configured, checkpoint taken — pack it:

smolvm machine stop --name agent-box
smolvm pack create --from-vm agent-box -o agent-box
smolvm pack push --file agent-box.smolmachine ghcr.io/you/agent-box:v1

The .smolmachine file pushes to any OCI registry. Or skip the registry entirely and ship a self-contained executable that boots in under 200 ms with nothing to install:

smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version

That last trick is the whole pitch in miniature: a complete, isolated, bootable environment as one file. Teammates run your exact agent sandbox with one command.

What you built

A hardware-isolated sandbox for AI agent work: a persistent microVM your agent drives through smolvm machine exec, checkpointed before risky steps, branched per experiment, fenced to a network allow-list, with secrets it can use but never read — and the whole thing packable into a single portable file. If you want to drive machines from your own code instead of the CLI, the SDKs (npm install smolmachines, pip install smolmachines, plus Rust and Go) expose one Machine API that runs in your process with no daemon, locally or on smol cloud:

import { Machine } from 'smolmachines';

const m = await Machine.create({ image: 'python:3.12-alpine', network: true });
const r = await m.exec(['python3', '-c', 'print(2 ** 10)']);
console.log(r.stdout); // 1024
await m.delete();

Honest limitations

No GPU. GPU and CUDA acceleration remain unavailable; the docs describe experimental API remoting, but GPU-heavy agent workloads need another path.
macOS Intel is out. No release build is published for it and it is untested — Apple Silicon or Linux it is.
Linux needs KVM. Without /dev/kvm (common on locked-down cloud VMs without nested virtualization), machines will not boot. The installer warns you up front.
Checkpoints are heavy. They capture RAM, CPU state, and disks — checkpoint your lean base state, not a machine that has ballooned to gigabytes of RAM.
Branching needs intent. Start with --branchable, and on Windows branches need --freeze-source.
smolvm is the open-source runtime behind the commercial smol machines cloud — local use is free and Apache-2.0, which is all this guide needs.

Frequently asked questions

How is smolvm different from Docker?

Docker isolates workloads with namespaces on a shared host kernel; smolvm gives every workload its own virtual machine and guest kernel (libkrun as the VMM, libkrunfw supplying the kernel) — true hardware isolation. The project’s comparison table puts boot time under 200 ms to agent-ready versus about 100 ms for containers, and there is no daemon to run: images are plain OCI and boot directly.

Can I drive machines from my own code instead of the CLI?

Yes. The SDKs — npm install smolmachines, pip install smolmachines, cargo add smolmachines, and a Go module — expose one Machine API that runs in your process with no daemon, locally or on smol cloud. You can create a machine, exec commands, and delete it from a few lines of code.

Can I move a running machine to another host?

Yes — checkpoints are portable. Save one with smolvm machine checkpoint, then restore it on another host or on smol cloud; the project documents resuming an arm64 Mac checkpoint on arm64 Linux. You can also rewind a machine to an earlier checkpoint generation with --from <checkpoint> --at '~N'.