smol machines
Ship and run software with isolation by default.
DocsGitHub

about ​

This is a CLI tool that lets you:

  1. Manage and run custom Linux virtual machines locally with: sub-second cold start, cross-platform (macOS, Linux), elastic memory usage.
  2. Pack a stateful virtual machine into a single file (.smolmachine) to rehydrate on any supported platform.

install + usage ​

bash
# install (macOS + Linux)
curl -sSL https://smolmachines.com/install.sh | bash

# for coding agents — install + discover all commands
curl -sSL https://smolmachines.com/install.sh | bash && smolvm --help
bash
# run a command in an ephemeral VM (cleaned up after exit)
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"

# interactive shell
smolvm machine run --net -it --image alpine -- /bin/sh
# inside the VM: apk add sl && sl && exit

# uninstall
curl -sSL https://smolmachines.com/install.sh | bash -s -- --uninstall

use this for ​

sandbox untrusted code — run untrusted programs in a hardware-isolated VM. Host filesystem, network, and credentials are separated by a hypervisor boundary.

bash
# network is off by default — untrusted code can't phone home
smolvm machine run --image alpine -- ping -c 1 1.1.1.1
# fails — no network access

# lock down egress — only allow specific hosts
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
# works — allowed host

smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com
# fails — not in allow list

pack into portable executables — turn any workload into a self-contained binary. All dependencies are pre-baked — no install step, no runtime downloads, boots in <200ms.

bash
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — isolated, no pyenv/venv/conda needed

persistent machines for development — create, stop, start. Installed packages survive restarts.

bash
smolvm machine create --net myvm
smolvm machine start --name myvm
smolvm machine exec --name myvm -- apk add sl
smolvm machine exec --name myvm -it -- /bin/sh
# inside: sl, ls, uname -a — type 'exit' to leave
smolvm machine stop --name myvm

use git and ssh without exposing keys — forward your host SSH agent into the VM. Private keys never enter the guest — the hypervisor enforces this. Requires an SSH agent running on your host (ssh-add -l to check).

bash
smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# lists your host keys, but they can't be extracted from inside the VM

smolvm machine exec --name myvm -- git clone [email protected]:org/private-repo.git

declare environments with a smolfile — reproducible VM config in a simple TOML file.

bash
# Smolfile
# image = "python:3.12-alpine"
# net = true
# [network]
# allow_hosts = ["api.stripe.com", "db.example.com"]
# [dev]
# init = ["pip install -r requirements.txt"]
# volumes = ["./src:/app"]
# [auth]
# ssh_agent = true

smolvm machine create myvm -s Smolfile
smolvm machine start --name myvm

More examples: python · node · doom

comparison ​

smolvmContainersColimaQEMUFirecrackerKata
IsolationVM per workloadNamespace (shared kernel)Namespace (1 VM)Separate VMSeparate VMVM per container
Boot time<200ms~100ms~seconds~15-30s<125ms~500ms
ArchitectureLibrary (libkrun)DaemonDaemon (in VM)ProcessProcessRuntime stack
Per-workload VMsYesNoNo (shared)YesYesYes
macOS nativeYesVia Docker VMYes (krunkit)YesNoNo
Embeddable SDKYesNoNoNoNoNo
Portable artifacts.smolmachineImages (need daemon)NoNoNoNo

Sources: container isolation · containerd benchmark · QEMU boot time · Firecracker · Kata Containers · Kata boot time · Firecracker requires KVM · Kata macOS support

how it works ​

Each workload gets real hardware isolation — its own kernel on Hypervisor.framework (macOS) or KVM (Linux). Pack it into a .smolmachine and it runs anywhere the host architecture matches, with zero dependencies.

Defaults: 4 vCPUs, 8 GiB RAM. Memory is elastic via virtio balloon — the host only commits what the guest actually uses and reclaims the rest automatically. vCPU threads sleep in the hypervisor when idle, so over-provisioning has near-zero cost. Override with --cpus and --mem.

libkrun VMM + custom kernel: libkrunfw. No daemon process — the VMM is a library linked into the smolvm binary.

platform support ​

hostguestrequirements
macOS Apple Siliconarm64 LinuxmacOS 11+
macOS Intelx86_64 LinuxmacOS 11+ (untested)
Linux x86_64x86_64 LinuxKVM (/dev/kvm)
Linux aarch64aarch64 LinuxKVM (/dev/kvm)

Apache-2.0 · made by @binsquare · twitter · github

Apache-2.0