SmolVM - Portable MicroVMs Without the Headaches

We’ve all been there: a project builds perfectly on your laptop, but the moment your colleague clones it, everything breaks. For years, containers (like Docker) have been the go-to solution for this. But what if you want stronger hardware-level isolation, real persistence for your development environment and the ability to literally “ship your machine” as a single executable file? There comes SmolVM, an open-source, Rust-powered CLI tool that lets you build, run and pack lightweight virtual machines. It mixes the ergonomics of containers with the isolation of traditional VMs, booting up in a few hundreds of milliseconds.

What Makes SmolVM Different?

Under the hood, SmolVM leverages libkrun to provide true hardware isolation. Depending on your OS, it will spin up a dedicated kernel using KVM (Linux) or the native Hypervisor framework (macOS).

Unlike traditional heavyweight VMs like VirtualBox that take seconds or minutes to boot, SmolVM instances start in a fraction of a second. They are completely independent of a Docker daemon but still pull natively from registries like Docker Hub. Furthermore, memory is allocated elastically via a virtio balloon, meaning your host only allows the RAM the VM actively uses.

Building Your First MicroVM

To see the magic in action, let’s build a customized Python development environment.

First, install the CLI:

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

Next, instead of a Dockerfile, SmolVM uses a TOML configuration called a Smolfile. Create a file named Smolfile in your project root:

image = "python:3.12-slim"
net = true

[network]
allow_hosts = []

[dev]
init = [
  "apt-get update",
  "apt-get install -y zsh git curl",
  # Install Oh My Zsh silently
  '''sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" || true''',
  # Enable a custom coloured theme
  '''sed -i 's/ZSH_THEME=.*/ZSH_THEME="alanpeabody"/' /root/.zshrc''',
  "chsh -s /usr/bin/zsh",
  "echo myvm > /etc/hostname"
]
volumes = ["./src:/app"]

[auth]
ssh_agent = true

Here is what is declared in this Smolfile:

• Base Image: we are bootstrapping directly from the python:3.12-slim container image.
• Init Scripts: the [dev] block runs exactly once when the VM is created. We use it to install zsh, git and ohmyzsh to make the shell environment comfortable.
• Volume Mounts: we mount our local ./src directory into the VM at /app.
• Zero-Leak SSH: setting ssh_agent = true lets the VM use your host SSH agent for Git/SSH while keeping private keys on the host, since the hypervisor only forwards the agent socket (requires an SSH agent running on your host, run ssh-add -l to check).

Don’t forget to include the src directory inside your project root:

mkdir src

Firing It Up

Creating and entering the VM takes just a few commands:

# Create the machine based on our Smolfile
smolvm machine create myvm --smolfile Smolfile

# Boot it up (pulling the image and running init
# scripts are the most time-consuming actions)
smolvm machine start --name myvm

# Drop into our customized zsh shell
smolvm machine exec -it --name myvm -- zsh

At this point, you have a fully functional, hardware-isolated Linux sandbox. You can install pip packages and do your normal development. You can also replace the zsh command here above with any other one you’d like to execute.

The Superpower: Packing Your Machine

Here is where SmolVM truly outshines traditional workflows. What if you want to share zsh, Python dependencies and system configurations with a coworker?

You can freeze the VM and pack it into a portable executable:

# Stop the running machine
smolvm machine stop --name myvm

# Pack the VM into a single binary
smolvm pack create --from-vm myvm -o myvm-packed

This generates a binary myvm-packed and a myvm-packed.smolmachine sidecar. You can use --single-file to pack everything as a single file (no sidecar). This is simpler to distribute but may have issues with macOS notarization. The executable contains the microVM, the filesystem state and all the required runtime logic. Anyone who shares the same CPU architecture as yours can now download this single file and run:

./myvm-packed run -it -- zsh

No dependencies. No installation steps. No Docker daemon required. They simply execute the file and instantly drop into the exact same isolated Python 3.12 environment you created.

Cleaning

Removing a machine is easy:

# Get the list of created machines
smolvm machine list

# Remove your machine with a specific <name>
smolvm machine delete <name>

Conclusion

SmolVM bridges a gap between the speed of containers and the isolation of VMs. Whether you are sandboxing untrusted AI-generated code, locking down network egress for security testing, or simply trying to distribute a bulletproof dev environment to your team without making them read a README, SmolVM might offer a remarkably clean developer experience.

References

• https://korben.info/smolvm-microvm-portable-rust.html
• https://github.com/smol-machines/smolvm

This blog post is licensed under CC BY-SA 4.0