Run microVMs locally to sandbox workloads.
Alpha - APIs can change, there may be bugs. Report issues
# install (macOS only, Linux coming soon)
curl -sSL https://smolmachines.com/install.sh | bash
# sandbox - ephemeral isolated environments
smolvm sandbox run --net alpine:latest -- echo "hello"
smolvm sandbox run --net -v /tmp:/workspace alpine:latest -- ls /workspace
smolvm sandbox run --net python:3.12-alpine -- python -V
# microvm - persistent linux VMs
smolvm microvm start
smolvm microvm exec -- echo "hello"
smolvm microvm stop
# pack - build a portable, executable virtual machine.
smolvm pack alpine:latest -o ./my-sandbox # creates ./my-sandbox + ./my-sandbox.smolmachine
smolvm pack alpine:latest -o ./my-sandbox --single-file # single executable, no sidecar
./my-sandbox uname -a # this will return results of running sys info within the guest linux vm
smolvm pack python:3.12-alpine -o ./my-pythonvm
./my-pythonvm python3 -c "import sys; print(sys.version)"
# uninstall
curl -sSL https://smolmachines.com/install.sh | bash -s -- --uninstallmicroVMs are lightweight VMs - security and isolation of VMs with the speed of containers.
They power AWS Lambda and Fly.io, but are inaccessible to average developers due to setup complexity.
smolVM makes microVMs easy: <250ms boot, works on macOS and Linux, single binary distribution.
- run coding agents locally and safely
- run microVMs locally on macOS and Linux with minimal setup
- run containers within microvm for improved isolation
- distribute self-contained sandboxed applications
| Containers | QEMU | Firecracker | Kata | smolvm | |
|---|---|---|---|---|---|
| kernel isolation | shared ¹ | separate | separate | separate | separate |
| boot time | ~100ms ² | ~15-30s ³ | <125ms ⁴ | ~500ms ⁵ | <250ms |
| setup | easy | complex | complex | complex | easy |
| macOS | via Docker | yes | no ⁶ | no ⁷ | yes |
| guest rootfs | layered | disk image | DIY ⁸ | bundled + DIY | bundled |
| embeddable | no | no | no | no | yes |
| distribution | daemon+CLI ⁹ | multiple | binary+rootfs | runtime stack ¹⁰ | single binary |
References
libkrun VMM + Hypervisor.framework (macOS) / KVM (Linux) + crun container runtime.
| host | guest | requirements |
|---|---|---|
| macOS Apple Silicon | arm64 Linux | macOS 11+ |
| macOS Intel | x86_64 Linux | macOS 11+ (untested) |
| Linux x86_64 | x86_64 Linux | KVM (/dev/kvm) |
| Linux aarch64 | aarch64 Linux | KVM (/dev/kvm) |
- Container rootfs writes: Writes to container filesystem (
/tmp,/home, etc.) fail due to a libkrun TSI bug with overlayfs. Writes to mounted volumes work. - Network is opt-in: Use
--netto enable outbound network access (required for image pulls from registries). TCP/UDP only — ICMP (ping) and raw sockets do not work. - Volume mounts: Directories only (no single files)
- macOS: Binary must be signed with Hypervisor.framework entitlements
File writes for coding agents:
# Works: top-level mount path
smolvm sandbox run --net -v /tmp:/workspace alpine:latest -- sh -c "echo 'hello' > /workspace/out.txt"
# Fails: nested mount path or container rootfs
smolvm sandbox run --net -v /tmp:/mnt/data alpine:latest -- sh -c "echo 'hello' > /mnt/data/out.txt"# build
./scripts/build-dist.sh
# run tests
./tests/run_all.shDatabase lock errors ("Database already open"):
pkill -f "smolvm serve"
pkill -f "smolvm-bin microvm start"Hung tests: Check for stuck VM processes:
ps aux | grep smolvmApache-2.0