smolvm
Ship and run software with isolation by default.
This is a CLI tool that lets you:
- Manage and run custom Linux virtual machines locally with: sub-second cold start, cross-platform (macOS, Linux, Windows), elastic memory usage.
- Pack a stateful virtual machine into a single file (.smolmachine) to rehydrate on any supported platform.
Install
# 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 --helpOr download from GitHub Releases, and place it into ~/.local/share/.
Windows: download the windows-x86_64 release (bundles krun.dll + libkrunfw.dll), unzip it, and run smolvm.exe. Requires the Windows Hypervisor Platform (WHP) feature enabled.
Quick Start
# 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 && exitUse This For
Sandbox untrusted code — run untrusted programs in a hardware-isolated VM. Host filesystem, network, and credentials are separated by a hypervisor boundary.
# network is off by default — untrusted code can't phone home
smolvm machine run --image alpine -- nslookup example.com
# 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 listPack 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.
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — isolated, no pyenv/venv/conda neededUse local container images — for CI, air-gapped hosts, and fast iteration. Feed --image a docker save / podman save archive, pipe one on stdin, or point it at an unpacked rootfs directory. Image work is delegated to your container tooling; smolvm just boots the result.
# build locally, run in the VM with no push/pull
docker build -t myapp .
docker save myapp | smolvm machine run --image - -- ./app
# from an archive file (boots with no network)
smolvm machine run --image ./myapp.tar -- ./app
# from an already-unpacked rootfs directory
smolvm machine run --image ./rootfs/ -- ./appPersistent machines for development — create, stop, start. Installed packages survive restarts.
smolvm machine create --net --name 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 myvmUse git and SSH without copying private keys into the guest. Forward your host SSH agent into the VM. The guest can ask the agent to sign with any forwarded key while the socket is available, so forward it only to workloads you trust. Requires an SSH agent running on your host (ssh-add -l to check).
smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# lists your host keys; private key material remains in the host agent
smolvm machine exec --name myvm -- git clone git@github.com:org/private-repo.gitDeclare environments with a Smolfile — reproducible VM config in a simple TOML file.
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 = truesmolvm machine create --name myvm -s Smolfile
smolvm machine start --name myvmMore examples: python · node · doom
How It Works
Each workload runs in a hardware-virtualized VM with its own guest kernel on Hypervisor.framework (macOS), KVM (Linux), or the Windows Hypervisor Platform (Windows). libkrun is the VMM and libkrunfw supplies the guest kernel. Pack it into a .smolmachine and it runs anywhere the host architecture matches, with zero dependencies.
Images use the OCI format — the same open standard Docker uses. Any image on Docker Hub, ghcr.io, or other OCI registries can be pulled and booted as a microVM. No Docker daemon required.
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.
Security Model
smolvm strengthens the guest/host boundary by giving each workload a separate VM and guest kernel. It is not, by itself, a hardened multi-user control plane:
- The
smolvmCLI and VMM processes run with the permissions of the invoking host user. That user account, the host OS, the hypervisor backend, libkrun, and smolvm are in the trusted computing base. - Host directories passed with
--volumeare intentionally exposed to the guest with the requested access. Do not mount secrets or sensitive paths into an untrusted workload. --ssh-agentdoes not copy private key material into the guest, but it grants the guest access to the forwarded agent socket and therefore the ability to request signatures while the VM is running.- Networking is disabled by default. Enabling
--net, port forwarding, or host services expands the workload's reachable surface. - In standalone local use, smolvm's state and control endpoints are scoped to the invoking user's environment. For hostile local co-tenants, add host-level account separation and OS confinement around the VMM process. This section does not describe the separate smolmachines cloud control plane or its tenant-isolation guarantees.
- Release archives publish SHA-256 checksums and the installer rejects a mismatch when the checksum file is available. Releases are not currently signed or accompanied by provenance attestations, and the installer permits installation when the checksum file cannot be downloaded.
Treat root in the guest as untrusted. The VM boundary limits its direct access to the host, while every explicitly forwarded capability, including mounts, network access, ports, and SSH agent access, becomes part of the workload's authority.
Comparison
| smolvm | Containers | Colima | QEMU | Firecracker | Kata | |
|---|---|---|---|---|---|---|
| Workload boundary | VM + guest kernel | Namespace + shared kernel | Namespace inside shared VM | VM + guest kernel | VM + guest kernel | VM per container |
| Boot time | <200ms | ~100ms | ~seconds | ~15-30s | <125ms | ~500ms |
| Architecture | Library (libkrun) | Daemon | Daemon (in VM) | Process | Process | Runtime stack |
| Per-workload VMs | Yes | No | No (shared) | Yes | Yes | Yes |
| macOS native | Yes | Via Docker VM | Yes (krunkit) | Yes | No | No |
| Embeddable SDK | Yes | No | No | No | No | No |
| Portable artifacts | .smolmachine |
Images (need daemon) | No | No | No | No |
Platform Support
| 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) |
| Windows x86_64 | x86_64 Linux | Windows Hypervisor Platform (WHP) enabled |
Known Limitations
- Network is opt-in (
--netonmachine create). TCP/UDP only, no ICMP. - Volume mounts: directories only (no single files). Mounting at
/workspace(-v /host/dir:/workspace) takes priority over the default storage-disk workspace — your host directory is used instead. - macOS: binary must be signed with Hypervisor.framework entitlements.
--ssh-agentrequires an SSH agent running on the host (SSH_AUTH_SOCKmust be set).- GPU acceleration requires libkrun built with
GPU=1and virglrenderer + a Vulkan driver on the host (see GPU Acceleration below). - Windows:
--networks the same as on other platforms (virtio-net with inbound port-forwarding; TSI for outbound-only VMs), as domachine exec/ interactive sessions andmachine stats. Not yet available on Windows: GPU acceleration andmachine fork/ snapshot. Pack create needsstorage-template.ext4/overlay-template.ext4next tosmolvm.exe(Windows has no hostmkfs.ext4).
GPU Acceleration
smolvm exposes the host GPU to guests via virtio-gpu / Venus (Vulkan-over-virtio). Guest workloads see a real Vulkan device; on Linux + Intel this renders as:
ANGLE (Intel, Vulkan 1.4 (Virtio-GPU Venus (Intel(R) UHD Graphics ...)), venus)
Host requirements
macOS — virglrenderer and MoltenVK are bundled in the smolvm distribution. No extra installs needed.
Linux — virglrenderer and a host Vulkan driver must be installed from the system package manager:
| Distro | Packages |
|---|---|
| Alpine | apk add virglrenderer mesa-vulkan-intel (or mesa-vulkan-ati for AMD) |
| Debian/Ubuntu | apt install virglrenderer0 mesa-vulkan-drivers |
virglrenderer depends on libEGL and libdrm from the host GPU driver stack — these are hardware-specific and cannot be bundled. Any GPU-capable Linux host will already have them installed via its GPU driver.
Usage
# CLI
smolvm machine run --gpu --image alpine -- vulkaninfo --summary
# Smolfile
# gpu = true
# gpu_vram = 2048 # MiB, default 4096The guest Vulkan loader must be pointed at the virtio ICD:
export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.jsonHeadless browser example
See examples/headless-browser/ for a working Chromium setup using ANGLE + Venus for hardware-accelerated WebGL inside a headless VM.
CUDA API Remoting
--gpu and --cuda provide different interfaces. --gpu exposes Vulkan through virtio-gpu / Venus; it does not provide CUDA. --cuda enables CUDA API remoting: driverless guest shims forward CUDA calls over vsock to a host process, which executes them through the host's NVIDIA driver.
CUDA remoting requires an NVIDIA GPU and a working NVIDIA driver on the host. It is not GPU passthrough: the guest receives neither the physical device nor an NVIDIA driver.
The VM boundary still isolates the workload's CPU, memory, and filesystem. GPU access is mediated by host processes and the shared host GPU, so GPU isolation remains process-level rather than a hardware or VM boundary. Do not treat CUDA remoting as a hardened multi-tenant GPU isolation boundary.
See GPU access by API remoting: how a driverless microVM runs CUDA for the design, trade-offs, and comparison with passthrough.
Development
See docs/DEVELOPMENT.md.
Apache-2.0 · made by @binsquare · twitter · github
