smol-machines/smolvmPortable, lightweight, self-contained virtual machine.
Ship and run software with isolation by default.
This is a CLI tool that lets you:
# 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
Or 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.
# 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
A Smolfile declares a machine in TOML — the equivalent of a Dockerfile or a
cloud-init file, but for a whole VM: image, resources, network policy, mounts,
ports, and setup commands in one checked-in file.
image = "python:3.12-alpine"
net = true
cpus = 4
memory = 4096
ports = ["8000:8000", "5173-5180:5173-5180"]
volumes = ["./src:/app"]
init = ["pip install -r /app/requirements.txt"]
[network]
allow_hosts = ["api.stripe.com", "pypi.org"]
[auth]
ssh_agent = true
smolvm machine create --name myvm -s Smolfile # or --smolfile <PATH>
smolvm machine start --name myvm
Port mappings accept a single port ("8080"), an explicit mapping ("8080:80"), or equal-length one-to-one ranges ("5173-5180:5173-5180"). A machine can publish at most 64 concrete mappings.
Unknown keys are rejected rather than ignored, so a typo fails at create time instead of silently doing nothing.
Common keys: image, cpus, memory, net, ports, volumes, env,
init, workdir, gpu, cuda, docker_socket, storage, overlay, and the
[network], [dev], [auth], [health], [restart], [service] tables.
You don't need a Dockerfile to keep an environment. Set a machine up however you
like — by hand, or from a Smolfile — then pack the stopped machine into a
.smolmachine artifact and push it to any OCI registry:
smolvm machine shell --name myvm # install and configure interactively
smolvm machine stop --name myvm
smolvm pack create --from-vm myvm -o myvm
smolvm pack push --file myvm.smolmachine ghcr.io/you/myvm:v1
Anyone can then pull it and boot the exact same machine:
smolvm pack pull ghcr.io/you/myvm:v1
Working Smolfiles: python · node · docker-in-vm · local-llm · headless-browser · doom
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 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.
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — isolated, no pyenv/venv/conda needed
Use 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/ -- ./app
Persistent 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 myvm
Use 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 [email protected]:org/private-repo.git
Declare environments in a file — see Smolfile above for
reproducible machine config, and for snapshotting a configured machine into a
reusable .smolmachine image without writing a Dockerfile.
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.
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:
smolvm CLI 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.--volume are intentionally exposed to the guest with the requested access. Do not mount secrets or sensitive paths into an untrusted workload.--ssh-agent does 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.--net, port forwarding, or host services expands the workload's reachable surface.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.
| 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 |
| 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 |
--net on machine create). TCP/UDP only, no ICMP./workspace (-v /host/dir:/workspace) takes priority over the default storage-disk workspace — your host directory is used instead.com.apple.security.hypervisor). The shipped release is; a re-signed or freshly built binary silently loses it and every VM start then fails with krun_start_enter returned: -22 (EINVAL). Re-sign it (ad-hoc is fine): codesign --force --sign - --entitlements hv.entitlements <smolvm-bin> where hv.entitlements is a plist containing <key>com.apple.security.hypervisor</key><true/>.--ssh-agent requires an SSH agent running on the host (SSH_AUTH_SOCK must be set).GPU=1 and virglrenderer + a Vulkan driver on the host (see GPU Acceleration below).--net works the same as on other platforms (virtio-net with inbound port-forwarding; TSI for outbound-only VMs), as do machine exec / interactive sessions and machine stats. Not yet available on Windows: GPU acceleration and machine fork / snapshot. Pack create needs storage-template.ext4 / overlay-template.ext4 next to smolvm.exe (Windows has no host mkfs.ext4).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)
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.
# CLI
smolvm machine run --gpu --image alpine -- vulkaninfo --summary
# Smolfile
# gpu = true
# gpu_vram = 2048 # MiB, default 4096
The guest Vulkan loader must be pointed at the virtio ICD:
export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.json
See examples/headless-browser/ for a working Chromium setup using ANGLE + Venus for hardware-accelerated WebGL inside a headless VM.
--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.
Fork-heavy Linux hosts should use a kernel containing upstream KVM fix
916b7f4.
Affected kernels can intermittently report ENOMEM on the first KVM_RUN even
with ample host memory; smolvm reduces exposure and replaces a failed worker,
but the kernel update is the definitive fix.
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.
See docs/DEVELOPMENT.md.
Apache-2.0 · made by @binsquare · twitter · github