Skip to main content
This guide walks you from zero to a running sandbox. By the end, you will have SmolVM installed and a working example that creates an isolated environment, runs a command inside it, and cleans up automatically.
1

Check prerequisites

SmolVM uses hardware virtualization. The requirements depend on your platform:
  • KVM support — check with ls /dev/kvm
  • Ubuntu, Debian, or Fedora recommended
  • Root access for initial setup
If /dev/kvm does not exist, enable virtualization in your BIOS/UEFI settings. For cloud VMs, enable nested virtualization in your hypervisor.
2

Install SmolVM

pip install smolvm
3

Run one-time setup

This configures the virtualization backend for your machine:
smolvm setup
On Linux, this installs Firecracker, configures KVM permissions, and sets up networking tools. You may be prompted for sudo.On macOS, this installs QEMU via Homebrew.
4

Verify the runtime

Confirm everything is ready:
smolvm doctor
You should see green checkmarks for your backend, KVM (Linux), and networking tools.
5

Run your first sandbox

Create a file called quickstart.py:
quickstart.py
from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("echo 'Hello from the sandbox'")
    print(result.stdout.strip())
Run it:
python quickstart.py
You should see:
Hello from the sandbox
The with block handles the full lifecycle — it creates the sandbox on entry and tears it down on exit.
The first run takes longer (30–60 seconds) because SmolVM downloads and builds the Alpine Linux base image. Subsequent runs use the cached image and boot in under a second.

​
Try more commands

Inside the sandbox you can run as many commands as you need. The sandbox stays alive until the with block exits: 
from smolvm import SmolVM

with SmolVM() as vm:
    print(f"VM ID: {vm.vm_id}")
    print(f"VM IP: {vm.get_ip()}")

    # Install a package and use it
    vm.run("apk add curl")
    result = vm.run("curl -s https://httpbin.org/ip")
    print(result.stdout.strip())

# Sandbox is automatically stopped and deleted here

​
Customize resources

Configure memory and disk size for heavier workloads: 
from smolvm import SmolVM

with SmolVM(mem_size_mib=2048, disk_size_mib=4096) as vm:
    result = vm.run("free -m")
    print(result.stdout)
Default values:
  • Memory: 512 MiB
  • Disk: 512 MiB
  • Minimum disk size: 64 MiB

​
Next steps

AI agent integration

Plug SmolVM into PydanticAI, OpenAI Agents, LangChain, and more

Port forwarding

Expose services running inside a sandbox to your host machine

Custom images

Build specialized images with your own tools pre-installed

API reference

Explore the complete SmolVM API

​
Troubleshooting

Linux only — if you see “KVM device missing”:
  1. Check virtualization support: 
    # Intel CPUs
grep -E 'vmx' /proc/cpuinfo

# AMD CPUs
grep -E 'svm' /proc/cpuinfo
    If nothing appears, enable virtualization in BIOS/UEFI.
  2. Load KVM modules: 
    sudo modprobe kvm
sudo modprobe kvm_intel  # or kvm_amd for AMD
  3. Add your user to the kvm group: 
    sudo usermod -aG kvm $USER
newgrp kvm  # or log out and back in
If the sandbox starts but SSH times out:
  1. Wait longer — the first boot downloads and builds the Alpine image (30–60 seconds).
  2. Increase timeout: 
    vm = SmolVM()
vm.start(boot_timeout=60.0)
vm.wait_for_ssh(timeout=60.0)
  3. Check networking: 
    ip link show | grep tap
sudo nft list ruleset

brew install qemu
Then verify:
which qemu-system-aarch64  # Apple Silicon
which qemu-system-x86_64   # Intel
Join the Slack community to get help and share your use cases.
Last modified on April 6, 2026