SmolVM architecture overview

​

What happens when you run code

1. SmolVM builds or reuses a lightweight Linux image — a published preset such as Ubuntu, or a custom filesystem with your own tools.
2. A microVM boots using Firecracker on Linux or QEMU on macOS and Linux.
3. A private network is created so the sandbox can reach the internet but is isolated from other sandboxes.
4. SmolVM connects to the sandbox — over SSH, or a faster vsock channel when available — to execute your commands and return the output.
5. Everything is torn down when you exit the with block.

from smolvm import SmolVM

with SmolVM(memory=2048) as vm:
    result = vm.run("free -m")
    print(result.stdout)
# Sandbox automatically stopped and cleaned up

​

Why microVMs instead of containers

• Stronger boundary — each sandbox runs its own kernel, so a breakout would require a hypervisor exploit, not just a kernel vulnerability
• Fast startup — QEMU + vsock published Ubuntu sandboxes reach readiness in under half a second on the latest Linux benchmark
• Low overhead — minimal memory footprint compared to traditional VMs

​

Key components

​

SDK (SmolVM class)

​

CLI (smolvm command)

​

Network layer

​

State store

​

Image builder

​

Resource defaults

# Customize resources
with SmolVM(memory=2048, disk_size=4096) as vm:
    vm.run("echo 'more room to work'")

​

Performance

​

Next steps

• Learn about the security model
• Understand backend options (Firecracker vs. QEMU)
• Configure networking