Install SmolVM

Install SmolVM, prepare the machine that will run sandboxes, and confirm that it is ready. You need Python 3.11 or newer; supported host setup is Linux and macOS.

Install the package

pip install smolvm

Prepare your machine

On macOS, install QEMU first, then let SmolVM check the rest of the setup:

brew install qemu
smolvm setup
smolvm doctor

On Linux, setup installs or checks the runtime dependencies and configures what SmolVM needs to run sandboxes. It may ask for administrator permission.

smolvm setup
smolvm doctor

smolvm doctor reports problems and their recovery steps. Add --strict when a warning should fail an automated check.

Choose where Firecracker is stored

On Linux, Firecracker is the program that starts a sandbox. SmolVM stores it in ~/.smolvm/bin by default, which works without changing system folders.

Choose another folder for one setup run with:

smolvm setup --firecracker-dir "$HOME/.local/bin"

If that folder is not already on PATH, set it for future SmolVM commands:

export SMOLVM_FIRECRACKER_DIR="$HOME/.local/bin"
smolvm setup

This setting changes only the Firecracker location. Images still use SMOLVM_IMAGE_DIR, and sandbox state still uses SMOLVM_DATA_DIR.

Fedora Atomic desktops

Silverblue, Bluefin, and other Fedora Atomic systems can use the normal setup command when the required host tools are already installed. SmolVM does not change the rpm-ostree deployment automatically. If a tool is missing, setup prints the exact rpm-ostree command and asks you to reboot before retrying.

Prepare macOS desktop support

Apple Silicon Mac users can install the separate local desktop runtime:

smolvm setup --macos
smolvm doctor --backend vz

This is only needed for macOS guests. Linux guests on a Mac continue to use QEMU.

Build-machine setup

Use this only when preparing a reusable machine image on a builder that cannot run virtualization itself:

smolvm setup --for-bake --runtime-user ubuntu

After booting that image on the real runtime machine, run smolvm doctor before accepting work.

What SmolVM selects automatically

When you do not choose a backend, SmolVM picks the best one that is actually installed on your machine. It prefers Firecracker on Linux and QEMU on macOS, but if that one is missing it falls back to another installed backend, so it never picks something your machine cannot run. If nothing suitable is installed, smolvm sandbox create stops right away and tells you what to install — before downloading anything. You can inspect a specific choice with smolvm doctor --backend qemu or smolvm doctor --backend firecracker.

Implementation notes: supported setup platforms and packaged setup scripts are defined in src/smolvm/host/setup.py; backend selection is in src/smolvm/runtime/backends.py and is covered by tests/test_setup.py and tests/test_backends.py.