Hardware isolation
Each workload runs in a VM with its own guest kernel. Network access is off by default, and you decide which hosts, ports, folders and credentials cross the boundary.
Open-source microVM runtime
SmolVM for fast, isolated AI agent workloads.
Run lightweight Linux virtual machines inside your software, on your laptop, in the cloud, or on your own servers. SmolVM brings a real guest kernel, portable artifacts, and a developer-friendly API to secure workloads.
Independent guide based on the official SmolVM repository and Smol Machines.
$ smolvm machine run \
--net \
--image alpine \
-- uname -a
Linux smolvm 6.x x86_64 GNU/Linux
✓ isolated machine readyOCI imageown kernelno daemon
A small runtime with a wide surface
What is SmolVM?
SmolVM is an embeddable, portable and branchable virtual machine runtime. It is designed for AI agents, code execution, development environments and other workloads that benefit from a strong boundary without the weight of a traditional VM stack.
Fast and elastic
SmolVM uses libkrun and an elastic memory model. The official project documents portable machines that boot in under 200ms, while local machines boot in under a second.
Embeddable by design
Drive machines from a single API inside your own process. Official SDK paths are available for Node.js, Python and Rust, with no host daemon required.
Branchable machines
Checkpoint a running machine, rewind it, or create copy-on-write branches. This is useful for reinforcement learning rollouts and persistent agent workflows.
Built for real workloads
One machine model, many environments.
Develop locally, deploy to smol cloud, or self-host on your own infrastructure. The same SDK and `.smolmachine` artifact can travel with the workload.
AI agent sandboxes
Give an agent a disposable Linux environment to run code, browse, install packages and work with files while keeping the host outside the guest boundary.
Reinforcement learning
Fork a live machine into parallel episodes instead of booting every rollout from scratch, then score and release the pool.
Portable development
Package a configured machine into one portable artifact that can run on compatible hosts or be pushed to an OCI registry.
Persistent workloads
Keep files, installed packages and workspace state between sessions so an agent can continue where it left off.
Get running
Install SmolVM and launch a machine.
Choose the install path for your host, then use the CLI to run an OCI image. The commands below are adapted from the official repository.
macOSHomebrew
brew install smol-machines/tap/smolvmmacOS + Linuxinstaller
curl -sSL https://smolmachines.com/install.sh | bashWindowsx86_64
Download the Windows release,\nthen run smolvm.exeRun an Alpine Linux microVM
$ smolvm machine run --net --image alpine -- uname -aUse smolvm --help to discover the complete command surface.
Embed it
Use one Machine API from your app.
The official SDK examples create a machine, execute a command, read stdout, and delete the machine when the task is finished.
import { Machine } from 'smolmachines';
const machine = await Machine.create({
image: 'python:3.12-alpine',
network: true
});
const result = await machine.exec(['python3', '-c', 'print(2 ** 10)']);
await machine.delete();Security model
The VM is the boundary. Your policy completes it.
SmolVM gives each workload a separate VM and guest kernel. You still need to decide what the workload can access. Start with the smallest network, mount and credential policy that lets the task work.
Read the official safety guidance ↗NetworkOff by default
Allow named hosts or CIDR ranges only when needed.
KernelSeparate per workload
Guest processes do not share the host kernel.
CredentialsExplicit forwarding
Use credential substitution instead of exposing host secrets directly.
MountsChoose carefully
Every mounted folder becomes available to the workload.
Portable by default
From a configured VM to a `.smolmachine`.
Pack a machine after setup, push it to an OCI registry, or run it as a self-contained executable. Checkpoints can also be restored on another compatible host.
01
Configure
Set the image, resources, ports, mounts and network policy in a machine or Smolfile.
→
02
Checkpoint
Save RAM, CPU state and disks while the workload is running.
→
03
Pack
Create a portable `.smolmachine` artifact for a compatible host or registry.
Portable artifactCLI
smolvm machine stop --name dev
smolvm pack create --from-vm dev -o dev
smolvm pack push --file dev.smolmachine ghcr.io/you/dev:v1Know the trade-offs
SmolVM compared with common runtimes.
These comparisons summarize the official project documentation. Exact performance depends on host hardware, workload and configuration.
| Runtime | Boundary | Boot time | Embeddable SDK | Portable artifact |
|---|---|---|---|---|
| SmolVM | VM + guest kernel | <200ms portable* | Yes | .smolmachine |
| Containers | Shared kernel | ~100ms | No | Images |
| QEMU | VM + guest kernel | ~15–30s | No | No |
| Firecracker | VM + guest kernel | <125ms | No | No |
* The under-200ms figure refers to the portable `.smolmachine` path described by the official SmolVM README.
See the idea
A visual introduction to SmolVM.
Watch the linked overview, then use the official repository and documentation for current commands and platform requirements.
Questions, answered
SmolVM FAQ
Use the official project documentation as the source of truth for changing commands, releases and compatibility notes.
What is SmolVM used for?
SmolVM is useful for AI agent sandboxes, untrusted code execution, persistent workloads, reinforcement learning environments and portable development environments.
Does SmolVM replace containers?
It solves a different problem. Containers are lightweight processes that share a kernel; SmolVM gives each workload a VM and guest kernel. OCI images can still be used as the workload format.
What does “branchable” mean?
A running machine can be checkpointed, rewound or copied into a child machine using copy-on-write. This lets experiments start from the same live state.
Which operating systems are supported?
The official project documents macOS, Linux and Windows hosts. Requirements differ: macOS uses Hypervisor.framework, Linux uses KVM, and Windows uses Windows Hypervisor Platform.
Is SmolVM affiliated with other projects named SmolVM?
The official README says smolvm is the open-source runtime behind Smol Machines and is not affiliated with other projects named SmolVM.
Keep exploring