SmolVM

SmolVM: Ship and Run Software with Isolation by Default

In a world where software moves quickly and security matters just as much as speed, SmolVM emerges as a lightweight yet powerful CLI tool that makes sandboxed computing feel effortless. SmolVM lets you manage and run custom Linux virtual machines locally with sub-second cold starts, cross-platform support (macOS, Linux), and elastic memory usage. The magic sauce lies in packing a stateful virtual machine into a single portable file (a .smolmachine) so you can rehydrate workloads on any supported host without chasing dependencies.

If you’re looking for a compact, production-friendly way to run untrusted code, develop in isolated environments, or simply experiment with lightweight VMs that boot in the blink of an eye, SmolVM is designed to be your go-to companion. It brings hardware-enforced isolation to the foreground, while keeping the developer experience crisp and approachable.

What SmolVM Delivers

• Real hardware isolation per workload: each VM has its own kernel, running on a hypervisor-backed foundation (Hypervisor.framework on macOS, KVM on Linux). This means strong boundaries between guest workloads and the host.
• Sub-second cold start: fast boot times make iterative development and testing feel instant.
• Portable, self-contained artifacts: workloads can be packed into a single .smolmachine file, enabling portability across supported hosts with zero runtime downloads.
• OCI-compatible images: you can boot any OCI image (Docker-style) from registries like Docker Hub or ghcr.io, without needing a running Docker daemon.
• Elastic memory usage: memory is managed with virtio ballooning, ensuring the host commits only what the guest actually uses.
• A broad spectrum of use cases: from sandboxing untrusted code to creating reusable development environments, to forwarding your host SSH agent into a VM without leaking private keys.

Getting Started: Quick Installation

Install SmolVM on macOS or Linux with a few commands (one-liners that fetch the official installer):

• Install (macOS + Linux)
• curl -sSL https://smolmachines.com/install.sh | bash
• For coding agents — install and discover all commands
• curl -sSL https://smolmachines.com/install.sh | bash && smolvm --help

If you prefer a manual route, you can also download from GitHub Releases and install from there.

Running Your First Ephemeral VM

SmolVM makes it easy to run a command inside a fresh VM that is automatically cleaned up after exit:

• Ephemeral VM with a simple command
• smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"
• Interactive shell inside a VM
• smolvm machine run --net -it --image alpine -- /bin/sh
• Inside the VM you might install a little tool, e.g., apk add sl, then run sl and explore

Use This For: Real World Scenarios

• Sandboxing untrusted code
• Network isolation is on by default. The VM is a hardware-isolated boundary from the host.
• Example: run a DNS lookup in a non-networked VM and observe failure when network access is blocked.
• Tight, portable work units
• Pack a workload into a portable executable — a self-contained binary with all dependencies baked in.
• Example: pack a Python environment into a single .smolmachine and run python3 --version without any Pyenv or virtualenv setup.
• Persistent development environments
• Create a VM, stop it, and restart later with packages and state preserved.
• Example: install packages, stop, start again, and continue development without reinstalling.
• SSH and Git without exposing keys
• Forward your host SSH agent into the VM so private keys never enter the guest. The hypervisor enforces key isolation.
• Example: clone a private repository from inside the VM using your host’s SSH agent.
• Declarative environments with Smolfile
• Describe a VM configuration in TOML and reproduce it reliably.
• Example: set image, network, volume mounts, and SSH agent support in a Smolfile.

Pack into Portable Executables

One of SmolVM’s distinguishing features is the ability to bake a workload into a single, self-contained binary (.smolmachine). All dependencies are pre-baked, there is no install step, no runtime downloads, and the VM boots in less than 200 milliseconds. This makes it straightforward to share workloads across machines and teams without worrying about environment drift.

Example workflow:

• Create a portable VM from an image
• smolvm pack create --image python:3.12-alpine -o ./python312 ./python312
• Run the packed workload
• run -- python3 --version
• You’ll see Python 3.12.x — isolated, with no pyenv/venv/conda needed

Persistent Machines for Development

Developers often want an environment that persists between sessions. SmolVM supports creating, starting, stopping, and reusing VMs while preserving installed packages and state. This is ideal for iterative development cycles where you install tools, run tests, and re-enter the same environment later.

A typical workflow:

• Create and start a persistent VM
• smolvm machine create --net myvm
• smolvm machine start --name myvm
• Work inside the VM
• smolvm machine exec --name myvm -- apk add sl
• smolvm machine exec --name myvm -it -- /bin/sh
• Inside: explore commands such as sl, ls, uname -a; type exit to leave
• Stop when done
• smolvm machine stop --name myvm

Using Git and SSH Without Exposing Keys

SmolVM supports SSH agent forwarding so private keys never enter the guest. This makes it comfortable to pull private repos or perform authenticated actions from within the VM without compromising host security.

Illustrative workflow:

• Start with SSH agent available inside the VM
• smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
• This lists your host keys from inside the VM, but they cannot be extracted from there
• Operate Git inside the VM
• smolvm machine exec --name myvm -- git clone git@github.com:org/private-repo.git

Declare Environments with a Smolfile

SmolVM supports a lightweight, reproducible VM configuration format called Smolfile, written in TOML. Include image, networking, volume mounts, and optional SSH agent settings in a single file to reproduce environments reliably.

Smolfile example (TOML):

• 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

To use it, you’ll typically run commands like:

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

If you want more examples, SmolVM maintains a variety of repositories with Python, Node, and other workloads you can adapt to your needs.

How It Works

SmolVM is designed around the principle of real hardware isolation for workloads. Each workload gets its own kernel, running on a hypervisor-backed foundation:

• macOS uses Hypervisor.framework, with libkrun as the VMM and libkrunfw as the kernel helper.
• Linux uses KVM to provide the virtualized environment.
• The VM is packaged as a .smolmachine file, which is portable and self-contained.
• Images use the OCI format (the same standard Docker uses), allowing you to pull any OCI-compatible image from registries such as Docker Hub or ghcr.io.
• No Docker daemon is required to boot VMs from OCI images.

Resource management is practical and forgiving:

• Defaults are conservative for broad compatibility: 4 vCPUs and 8 GiB RAM.
• Memory can be elastic thanks to virtio ballooning, so the host commits only what the guest uses.
• When idle, vCPU threads sleep in the hypervisor, reducing waste in over-provisioned environments.
• You can override defaults with --cpus and --mem to fit your workload.

Platform and Architecture Support

SmolVM is designed for cross-platform operation, but specifics vary by host and guest architecture:

• Host: macOS Apple Silicon (arm64) and macOS Intel (x8664); Linux x8664 and Linux aarch64
• Guest: Linux x86_64 and aarch64, with guest support aligned to the host architecture
• macOS guests (where supported) leverage the Hypervisor.framework path
• Linux guests require KVM support, accessed via /dev/kvm on compatible hosts

In short, SmolVM aims to align guest architecture with host architecture to keep the experience seamless and consistent.

Known Limitations

No system is perfect out of the box, and SmolVM has clear boundaries to help users plan accordingly:

• Network is opt-in via --net for a VM, and only supports TCP/UDP (no ICMP by default).
• Volume mounts currently support directories (not single files) for simplicity and security.
• On macOS, the binary must be signed with Hypervisor.framework entitlements.
• The --ssh-agent feature requires an SSH agent running on the host (SSHAUTHSOCK must be set).
• GPU acceleration requires libkrun built with GPU=1 and a compatible virglrenderer plus a Vulkan driver on the host.

GPU Acceleration

SmolVM exposes host GPUs to guests through virtio-gpu (Venus), enabling Vulkan-based workloads inside the VM. This is particularly compelling for workloads like 3D rendering or browser workloads that rely on WebGL.

• How it manifests inside the guest: the Vulkan loader points to the virtio ICD (native Vulkan on the host is leveraged through Venus).
• Local host requirements:
• macOS: virglrenderer and MoltenVK are bundled with SmolVM, no extra installs needed.
• Linux: virglrenderer and a host Vulkan driver must be installed via the distro’s package manager (examples shown below).
• Typical Linux package examples:
• Alpine: apk add virglrenderer mesa-vulkan-intel (or mesa-vulkan-ati for AMD)
• Debian/Ubuntu: apt install virglrenderer0 mesa-vulkan-drivers
• Important: virglrenderer depends on host GPU driver stack libraries (libEGL, libdrm). These are not bundled and must be present on the host.

To enable GPU within a VM, you might run:

• smolvm machine run --gpu --image alpine -- vulkaninfo --summary
• The guest Vulkan loader can be pointed at the virtio ICD with:
• export VKICDFILENAMES=/usr/share/vulkan/icd.d/virtioicd.x8664.json

Headless Browser Example

For workloads that require hardware-accelerated browsing or WebGL, SmolVM can support headless browser scenarios. See the examples/headless-browser directory for a working Chromium setup that uses ANGLE + Venus for hardware-accelerated WebGL inside a headless VM.

Development and Documentation

SmolVM provides a path for developers to contribute and document the project:

• Development resources are described in docs/DEVELOPMENT.md within the repository.
• The project is distributed under the Apache-2.0 license.
• Credits: made by BinSquare (@binsquare), with social links to Twitter and GitHub.

How to Approach SmolVM: A Typical Developer Journey

• Start with a simple ephemeral VM
• This is ideal for one-off experiments, script testing, or running a package manager in isolation.
• Move toward a persistent development VM
• Install tools you rely on, and stop/start sessions while keeping the environment intact.
• Explore packing options
• If you have a workload you want to share or deploy, packaging it as a portable .smolmachine can simplify distribution and execution.
• Integrate with your existing workflow
• Use Smolfile to declare environments that match your CI or local dev needs, ensuring reproducibility across machines.
• Leverage SSH agent forwarding for secure workflows
• Access private repositories from inside the VM without exposing private keys to the guest environment.

A Glimpse at the Architecture

• The workload runs inside its own VM with a dedicated kernel boundary.
• The hypervisor layer is provided by Hypervisor.framework (macOS) or KVM (Linux).
• A lightweight VMM stack (libkrun and libkrunfw) orchestrates the VM lifecycle.
• Images are OCI-compatible, aligning with a familiar container image ecosystem but without requiring a Docker daemon.
• The .smolmachine packaging format encapsulates the VM state and configuration, enabling portability across compatible hosts.

Why SmolVM Stands Out

• Isolation by default: every workload runs in its own VM boundary, delivering stronger isolation than shared-kernel containerization.
• Portability without dependency management: a single .smolmachine can move across compatible hosts without re-installation.
• Simplicity of use: the command surface is approachable, with pragmatic defaults that fit common workflows.
• Flexibility across workflows: from quick experiments to robust development environments, SmolVM supports diverse needs.

A Note on the Visual Identity

The SmolVM branding emphasizes clarity and speed. The logo at the top of the page is a visual anchor for the project, paired with badges that provide quick access to community and release information. If you’re sharing SmolVM in talks or documentation, including the logo and badges helps readers connect with the project’s identity and latest updates.

Conclusion: Embracing Small, Fast, and Secure VMs

SmolVM brings a practical, developer-friendly approach to sandboxed computing. It recognizes the value of hardware-enforced isolation while keeping the experience nimble and portable. With sub-second boots, portable VM artifacts, and a declarative Smolfile workflow, SmolVM makes it straightforward to run, share, and reproduce workloads in a secure and isolated manner.

Whether you’re sandboxing untrusted code, developing a reproducible environment, or experimenting with GPU-accelerated workloads inside a lightweight VM, SmolVM offers an elegant path forward. By blending familiar image-based workflows with a minimal, fast execution environment, it helps developers move quickly while maintaining strong security boundaries. The project welcomes contributions, experimentation, and feedback from users across macOS and Linux ecosystems.

If you’re curious to learn more or want to participate in the community, explore the SmolVM repository, join the Discord, and check out the latest releases. The journey toward reliable, portable, and isolated workloads begins with a single command or a single .smolmachine file—and SmolVM is here to make that journey smooth, fast, and repeatable.