Install SmolVM on Linux or macOS

Install SmolVM on Linux or macOS using the install script, pip, or build from source — sets up the Firecracker or QEMU backend automatically based on your platform.

SmolVM runs your code inside a fast, secure virtual machine. Under the hood it uses Firecracker on Linux and QEMU on macOS — both are tools for running isolated virtual machines. You don’t need to pick one; SmolVM detects your platform automatically.

Quick install

Install SmolVM with a single command:

curl -sSL https://celesto.ai/install.sh | bash

This installs everything you need (including Python), configures your machine, and verifies the setup.

Manual install

If you prefer to install step by step:

pip install smolvm
smolvm setup
smolvm doctor

On supported Linux and macOS systems, pip install smolvm pulls in the matching smolvm-core wheel automatically — most users do not need Rust installed.

Linux may prompt for sudo during smolvm setup to install host dependencies (Firecracker, nftables, iproute2) and configure runtime permissions. On macOS, setup installs QEMU via Homebrew.

After setup on Linux, activate your new KVM group membership with newgrp kvm, or log out and back in.

Install from source

Build SmolVM from source when you want the latest unreleased changes, or when you plan to modify SmolVM itself. This compiles the Rust helper package (smolvm-core) locally instead of downloading a prebuilt wheel.

You need Git, uv (the Python package manager SmolVM uses), and the Rust toolchain.

1. Clone the repository

   git clone https://github.com/CelestoAI/SmolVM.git
   cd SmolVM
   
2. Build and install

   uv sync --extra dev
   

   This creates a virtual environment, installs SmolVM’s dependencies, and compiles smolvm-core from the Rust sources in the checkout.

   Confirm the local build loaded correctly:

   uv run python -m smolvm_core
   

   It prints a report of the native helpers available on your machine.

3. Set up the host and verify

   uv run smolvm setup
   uv run smolvm doctor
   

   smolvm setup installs host dependencies — Firecracker on Linux, QEMU on macOS — and configures permissions. smolvm doctor confirms your machine is ready to run sandboxes.

Run source-built commands with uv run smolvm ... from the repository directory, so they use the build in your checkout. To use a plain smolvm command instead, activate the environment with source .venv/bin/activate.

Rebuild after changing Rust code with uv sync --reinstall-package smolvm-core, then rerun uv run python -m smolvm_core to confirm Python loads your new build.

For contribution guidelines, tests, and code style checks, see CONTRIBUTING.md.

Requirements

Linux

• Ubuntu, Debian, or Fedora (other distributions work but smolvm setup may not install host dependencies automatically)
• KVM support — the kernel feature that lets SmolVM run virtual machines. Check with ls /dev/kvm
• x86_64 architecture
• Python 3.10+

macOS

• macOS on Apple Silicon or Intel
• Homebrew
• Python 3.10+

When SMOLVM_BACKEND is unset or auto, SmolVM picks the best backend that is actually installed on your machine. It prefers Firecracker on Linux and QEMU on macOS, and falls back through Firecracker → QEMU → libkrun so it never resolves to a hypervisor your host cannot run.

If nothing suitable is installed, smolvm sandbox create fails immediately with a plain-English message telling you what to install — before downloading the base image, so a missing hypervisor no longer costs you a multi-hundred-MB download.

To force a specific backend:

export SMOLVM_BACKEND=firecracker   # or qemu, libkrun, or auto (the default)

Optional extras

Install extras for agent framework examples or the web dashboard:

pip install "smolvm[examples]"   # pydantic-ai, openai-agents, langchain, playwright
pip install "smolvm[dashboard]"  # fastapi, uvicorn, websockets
pip install "smolvm[all]"        # everything above

If you only need SmolVM as a sandbox, the base pip install smolvm is all you need.

Troubleshooting

Linux: KVM not available

If /dev/kvm doesn’t exist, enable virtualization:

sudo modprobe kvm_intel   # Intel CPUs
sudo modprobe kvm_amd     # AMD CPUs
ls -l /dev/kvm

For cloud VMs, enable nested virtualization in your hypervisor settings.

Linux: Permission denied on /dev/kvm

Add your user to the kvm group and activate it:

sudo usermod -aG kvm $USER
newgrp kvm

macOS: qemu-system not found

Ensure Homebrew’s bin directory is in your PATH:

export PATH="/opt/homebrew/bin:$PATH"   # Apple Silicon
export PATH="/usr/local/bin:$PATH"      # Intel

For golden-AMI builds, two-stage deploys, pinning the Firecracker version, and other non-default install paths, see the upstream installation guide.

Uninstall

pip uninstall smolvm
rm -rf ~/.local/state/smolvm ~/.smolvm

The rm -rf command deletes all sandbox state and cached images. Skip it if you might reinstall SmolVM later and want to keep your cached base images.

Next steps

Quickstart

Run your first sandbox in minutes

Basic usage

Learn about VM configuration options

Custom images

Build your own VM images with custom tools

API reference

Explore the complete API