Skip to main content
SmolVM supports two backends depending on your operating system:
  • Linux: Firecracker (KVM-based microVMs)
  • macOS: QEMU (hardware virtualization)
The backend is automatically detected based on your platform, but you can override it with the SMOLVM_BACKEND environment variable.

​
Requirements

​
System requirements

  • OS: Ubuntu, Debian, Fedora, or any Linux distribution with KVM support
  • Python: 3.10 or later
  • KVM: /dev/kvm must be accessible
  • Architecture: x86_64 (amd64)
  • Dependencies: ip, nft, ssh, wget, tar

​
Python dependencies

SmolVM requires the following Python packages (installed automatically via pip):
  • paramiko>=3.0 - SSH client for guest command execution
  • pydantic>=2.0 - Data validation and settings management
  • requests>=2.28 - HTTP client for API interactions
  • requests-unixsocket>=0.3 - Unix socket support for Firecracker API

​
Installation steps

1

Install Python package

pip install smolvm
2

Run one-time setup

Run the built-in setup command to install Firecracker and configure your system:
smolvm setup
Linux may prompt for sudo during setup so it can install host dependencies and configure runtime permissions.
The setup command performs the following operations:
  1. Checks KVM support: Verifies /dev/kvm exists
  2. Installs system dependencies: curl, wget, jq, nftables, iproute2, e2fsprogs, openssh-client, tar
  3. Downloads and installs Firecracker: Fetches the latest Firecracker binary and installs to /usr/local/bin
  4. Adds user to KVM group: Grants access to /dev/kvm
  5. Configures runtime sudoers: Sets up passwordless sudo for specific SmolVM commands (ip, nft)
You can also run the setup script directly from the cloned repository: sudo ./scripts/system-setup.sh --configure-runtime
3

Activate KVM group membership

After setup, activate the KVM group:
newgrp kvm
Or log out and log back in for the group changes to take effect permanently.
4

Verify installation

Check that everything is installed correctly:
# Check Firecracker
firecracker --version

# Check SmolVM
python -c "from smolvm import SmolVM; print('SmolVM installed successfully')"

# Run system diagnostics
smolvm doctor

​
Advanced installation options

​
Custom backend selection

You can override the automatic backend detection: 
# Force QEMU backend (useful for testing on Linux)
export SMOLVM_BACKEND=qemu

# Force Firecracker backend
export SMOLVM_BACKEND=firecracker

# Auto-detect (default)
export SMOLVM_BACKEND=auto
In Python: 
from smolvm import SmolVM

# Explicitly use QEMU backend
vm = SmolVM(backend="qemu")

​
Installing with Docker support

For building custom images, you may want Docker installed: 
sudo ./scripts/system-setup.sh --configure-runtime --with-docker

​
Optional extras

SmolVM includes optional dependency groups you can install depending on your use case: 
# Agent framework examples (PydanticAI, OpenAI Agents, LangChain, Playwright)
pip install "smolvm[examples]"

# Web dashboard for monitoring VMs
pip install "smolvm[dashboard]"

# Everything (dashboard + examples)
pip install "smolvm[all]"
ExtraWhat it includes
examplespydantic-ai, openai-agents, langchain, langchain-openai, openai, playwright
dashboardfastapi, uvicorn, websockets
allAll of the above
If you only need SmolVM as a sandbox and won’t use agent framework integrations, the base pip install smolvm is all you need.

​
Development install

For development with testing and linting tools: 
# Clone the repository
git clone https://github.com/CelestoAI/SmolVM.git
cd SmolVM

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Type checking
mypy src

​
Skip dependency installation

If you’ve already installed dependencies manually, skip the package manager step: 
sudo ./scripts/system-setup.sh --configure-runtime --skip-deps

​
Verifying your installation

​
System diagnostics

SmolVM includes a diagnostic tool to verify your setup: 
# Auto-detect backend and check dependencies
smolvm doctor

# Check specific backend
smolvm doctor --backend firecracker
smolvm doctor --backend qemu

# CI-friendly JSON output
smolvm doctor --json --strict

​
Test your first VM

Run a simple test to ensure everything works: 
from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("echo 'SmolVM is working!'")
    print(result.output)
    print(f"VM IP: {vm.get_ip()}")
    print(f"Status: {vm.status}")
If this runs without errors, your installation is complete!

​
Troubleshooting

If /dev/kvm doesn’t exist, ensure KVM is enabled:
# Check if KVM is loaded
lsmod | grep kvm

# For Intel CPUs
sudo modprobe kvm_intel

# For AMD CPUs
sudo modprobe kvm_amd

# Verify /dev/kvm exists
ls -l /dev/kvm
For cloud VMs, ensure nested virtualization is enabled in your hypervisor settings.
Add your user to the kvm group:
sudo usermod -aG kvm $USER
newgrp kvm
Verify group membership:
groups | grep kvm
Ensure /usr/local/bin is in your PATH:
echo $PATH
export PATH="/usr/local/bin:$PATH"

# Make permanent by adding to ~/.bashrc or ~/.zshrc
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
Ensure Homebrew’s bin directory is in your PATH:
# For Apple Silicon
export PATH="/opt/homebrew/bin:$PATH"

# For Intel
export PATH="/usr/local/bin:$PATH"

# Verify QEMU
which qemu-system-aarch64
Linux: Ensure nftables is installed and running:
sudo systemctl status nftables
sudo nft list ruleset
macOS: QEMU networking uses user-mode networking by default, which should work without additional configuration.
If the setup script fails during apt-get update, your repository sources may need updating:
# Check sources
cat /etc/apt/sources.list

# Update manually
sudo apt-get update

# If sources are broken, fix them first, then rerun with --skip-deps
sudo ./scripts/system-setup.sh --configure-runtime --skip-deps

​
Uninstallation

​
Remove the SmolVM Python package

pip uninstall smolvm

​
Remove system components (optional)

# Remove Firecracker binary
sudo rm /usr/local/bin/firecracker
sudo rm /usr/local/bin/jailer  # if installed

# Remove runtime sudoers configuration
sudo ./scripts/system-setup.sh --remove-runtime-config

# Remove user from KVM group (optional)
sudo deluser $USER kvm

# Clean up SmolVM data
rm -rf ~/.local/state/smolvm
rm -rf ~/.smolvm

​
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
Last modified on April 5, 2026