Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Requirements

  • 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+
The backend is selected automatically based on your platform (Firecracker on Linux, QEMU on macOS). To force a specific backend: 
export SMOLVM_BACKEND=auto   # or firecracker, 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

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.
Add your user to the kvm group and activate it:
sudo usermod -aG kvm $USER
newgrp kvm
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
Last modified on May 28, 2026