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 supports two backends for running sandboxes: Firecracker on Linux and QEMU on macOS. You usually don’t need to think about this — SmolVM picks the right one for your platform automatically.

​
How SmolVM picks a backend

SmolVM resolves the backend in this order:
  1. Explicit argument — SmolVM(backend="firecracker")
  2. Environment variable — SMOLVM_BACKEND=qemu
  3. Platform default — macOS uses QEMU, Linux uses Firecracker
The supported values are firecracker, qemu, and auto (the default).

​
Firecracker (Linux)

Firecracker is a lightweight virtual machine monitor built by AWS for serverless workloads. It starts sandboxes fast and uses very little memory, making it ideal for production and CI/CD.

​
Prerequisites

  • OS: Linux (Ubuntu, Debian, Fedora, etc.)
  • CPU: KVM support (Intel VT-x or AMD-V)
  • Kernel: Modern Linux kernel with KVM modules

​
Installation

# Install SmolVM
pip install smolvm

# Run system setup (installs Firecracker, configures KVM)
sudo ./scripts/system-setup.sh --configure-runtime

​
Strengths

  • Fast — sub-second boot (~572ms), ~43ms per command
  • Lightweight — minimal memory overhead, optimized for running many sandboxes
  • Secure — minimal attack surface, no legacy device emulation, trusted by AWS Lambda
  • Snapshots — fast snapshot and restore for checkpointing

​
Limitations

  • Linux only (requires KVM)
  • x86_64 or aarch64 architectures only
  • Minimal device emulation (by design)

​
Configuration

from smolvm import SmolVM

# Explicit Firecracker backend
vm = SmolVM(backend="firecracker")
vm.start()

​
Environment variable

# Force Firecracker backend
export SMOLVM_BACKEND=firecracker

python my_agent.py

​
QEMU (macOS)

QEMU is a mature, full-featured virtualizer that works across platforms. On macOS it uses Apple’s Hypervisor Framework (HVF) for near-native performance. It is also available on Linux for environments without KVM, and is the only backend for Windows guests.

​
Prerequisites

  • OS: macOS (or Linux without KVM)
  • Homebrew: For package management
  • QEMU: qemu-system-* binaries

​
Installation

# Install SmolVM
pip install smolvm

# macOS setup (installs QEMU via Homebrew)
./scripts/system-setup-macos.sh

# Optional: Explicit backend override
export SMOLVM_BACKEND=qemu

​
Strengths

  • Cross-platform — works on macOS, Linux, and Windows without KVM
  • Broad compatibility — emulates various architectures, extensive device support
  • Mature — well-tested, rich configuration and debugging tools

​
Limitations

  • Slower than Firecracker on Linux (~2-3s boot vs ~572ms)
  • Higher memory overhead
  • Larger binary and more moving parts

​
Configuration

from smolvm import SmolVM

# Explicit QEMU backend
vm = SmolVM(backend="qemu")
vm.start()

​
Environment variable

# Force QEMU backend (e.g., on Linux for testing)
export SMOLVM_BACKEND=qemu

python my_agent.py

​
Networking modes

The QEMU backend supports two networking modes, controlled by the qemu_network field on VMConfig:
  • "slirp" (default) — Userspace NAT with host port forwards. Works without root or extra host setup, which makes it the right choice for local macOS development.
  • "tap" — Linux-only. Attaches the guest to a host TAP device so it gets a real routable IP and falls under the same nftables NAT and isolation rules as Firecracker (egress masquerade, cross-sandbox drop, and IMDS block). Use this when you need Firecracker-level network isolation on a QEMU host — for example, running QEMU on a Linux production host for multi-tenant or untrusted workloads.
from smolvm import SmolVM, VMConfig
from pathlib import Path

config = VMConfig(
    kernel_path=Path("/path/to/vmlinux"),
    rootfs_path=Path("/path/to/rootfs.ext4"),
    backend="qemu",
    qemu_network="tap",  # Linux only; needs the same setup as Firecracker
)

with SmolVM(config) as vm:
    print(vm.run("ip -4 addr show eth0").stdout)
See network configuration for the host setup TAP mode reuses.

​
Comparison matrix

FeatureFirecrackerQEMU
Platform support
Linux✅ Native✅ Supported
macOS❌ Not supported✅ Native
Windows❌ Not supported✅ Supported
Performance
Boot time~572msSlower (~2-3s)
Command execution~43msSimilar
Memory overheadMinimalHigher
Features
KVM accelerationRequiredOptional
Snapshot/restore✅ Available✅ Available
Device emulationMinimalExtensive
Architecture supportx86_64, aarch64Many
Use cases
Production Linux✅ Recommended⚠️ Fallback
macOS development❌ Not available✅ Recommended
CI/CD (Linux)✅ Recommended⚠️ Testing only
CI/CD (macOS)❌ Not available✅ Only option

​
Backend diagnostics

SmolVM provides a diagnostic tool to check backend availability: 
# Auto-detect backend (Darwin -> qemu, Linux -> firecracker)
smolvm doctor

# Force backend checks
smolvm doctor --backend firecracker
smolvm doctor --backend qemu

# CI-friendly mode (JSON output)
smolvm doctor --json --strict
Example output: 
✅ Platform: linux
✅ Backend: firecracker
✅ KVM support: enabled
✅ Firecracker binary: /usr/local/bin/firecracker
✅ Network tools: ip, nft
✅ Sudo access: configured

​
Switching backends

​
Per-VM basis

from smolvm import SmolVM

# Use Firecracker
vm1 = SmolVM(backend="firecracker")

# Use QEMU
vm2 = SmolVM(backend="qemu")

​
Environment-wide

# In your shell or CI config
export SMOLVM_BACKEND=qemu

# All SmolVM instances will use QEMU
python my_script.py

​
Application-wide

import os

# Set before importing SmolVM
os.environ["SMOLVM_BACKEND"] = "firecracker"

from smolvm import SmolVM

vm = SmolVM()  # Uses Firecracker

​
Recommendations

​
For production (Linux)

Use Firecracker for production Linux deployments.
from smolvm import SmolVM

# Production configuration
vm = SmolVM(
    backend="firecracker",
    vcpu_count=2,
    memory=512,
    disk_mode="isolated"
)
Firecracker is the fastest option and has the smallest attack surface.

​
For development (macOS)

Use QEMU for local macOS development.
from smolvm import SmolVM

# Development configuration
vm = SmolVM(
    backend="qemu",  # Auto-detected on macOS
    memory=1024
)
QEMU is the only option on macOS and works well for local development.

​
For CI/CD

Linux runners: 
# .github/workflows/test.yml
steps:
  - name: Setup SmolVM
    run: |
      pip install smolvm
      sudo ./scripts/system-setup.sh --configure-runtime
  
  - name: Run tests
    run: |
      export SMOLVM_BACKEND=firecracker
      pytest tests/
macOS runners: 
steps:
  - name: Setup SmolVM
    run: |
      pip install smolvm
      ./scripts/system-setup-macos.sh
  
  - name: Run tests
    run: |
      export SMOLVM_BACKEND=qemu
      pytest tests/

​
Troubleshooting

​
”Unsupported backend” error

ValueError: Unsupported backend 'firecrackerr'. Supported values: auto, firecracker, qemu
Solution: Check spelling and use one of: auto, firecracker, qemu

​
KVM not available (Linux)

Error: KVM support not detected
Solution:
  1. Verify KVM modules: lsmod | grep kvm
  2. Check virtualization in BIOS
  3. Run system setup: sudo ./scripts/system-setup.sh --configure-runtime

​
QEMU not found (macOS)

Error: qemu-system-x86_64 not found
Solution: 
brew install qemu
# or run setup script
./scripts/system-setup-macos.sh

​
Wrong backend auto-selected

# Force specific backend
export SMOLVM_BACKEND=firecracker

# Or in code
vm = SmolVM(backend="firecracker")

​
Next steps

Last modified on June 2, 2026