Skip to main content
SmolVM is a lightning-fast, secure microVM runtime designed for high-density isolation. It provides AI agents and tools with a safe, hardware-virtualized environment to execute untrusted code without risking the host system.

​
✨ Features

  • 🔒 Secure Isolation: Hardware-level virtualization (utilizing Firecracker) for strong sandbox boundaries.
  • ⚡ Blazing Fast: MicroVMs boot in sub-second time with minimal overhead.
  • 🐍 Python Native: Clean, high-level SDK for managing VM lifecycles and command execution.
  • 🌐 Automatic Networking: Built-in NAT, port forwarding, and SSH tunneling.
  • 🛠️ Custom Images: Build specialized Debian-based rootfs images with your own tools.
  • 🧹 Auto-Cleanup: Integrated resource management to keep your host system clean.

​
🤔 Why SmolVM?

AI agents often need to execute arbitrary code (Python, JS, shell scripts) generated by LLMs. Running this code directly on your host or in standard containers can be risky.
  • MicroVM-based Security: Unlike containers that share the host kernel, SmolVM uses KVM-backed microVMs. This provides a significantly smaller attack surface and stronger hardware-level isolation.
  • Agent-First Design: SmolVM abstracts away the complexity of microVM networking, storage, and TAP devices into a simple, pythonic API.

​
🚀 Quickstart

​
Prerequisites

  • Linux + Firecracker backend: KVM support (Ubuntu/Debian/Fedora).
  • macOS + QEMU backend: Homebrew and QEMU (qemu-system-*).

​
Installation

pip install smolvm

​
Linux

git clone https://github.com/CelestoAI/SmolVM.git
sudo ./scripts/system-setup.sh --configure-runtime

​
MacOS

git clone https://github.com/CelestoAI/SmolVM.git
./scripts/system-setup-macos.sh

​
Basic Usage

Initialize a VM with no arguments for an auto-configured, SSH-ready environment: 
from smolvm import SmolVM

# Start sandboxed runtime
vm = SmolVM()
vm.start()

# Run ANY command like a real system
result = vm.run("echo 'Hello from the sandbox!'")
print(result.output)

# Stop the runtime
vm.stop()
Customize auto-config memory and disk size: 
from smolvm import SmolVM

# Use with context manager (auto start and deletes after use)
with SmolVM(mem_size_mib=2048, disk_size_mib=4096) as vm:
    print(vm.run("free -m").output)

​
Port Forwarding

Expose a guest application to your local machine securely. expose_local prefers host-local iptables forwarding and automatically falls back to an SSH tunnel when needed. 
from smolvm import SmolVM

with SmolVM() as vm:
    # Example: App in VM listening on port 8080, expose to host port 18080
    host_port = vm.expose_local(guest_port=8080, host_port=18080)
    print(f"App available at http://localhost:{host_port}")

​
Environment Variables

Inject environment variables into a running VM. Variables are persisted in /etc/profile.d/smolvm_env.sh and apply to new SSH/login shell sessions. 
from smolvm import SmolVM

with SmolVM() as vm:
    vm.set_env_vars({"API_KEY": "sk-...", "DEBUG": "1"})
    print(vm.list_env_vars())
    print(vm.run("echo $API_KEY").output)
CLI: 
smolvm env set <vm_id> API_KEY=sk-... DEBUG=1
smolvm env list <vm_id> --show-values
smolvm env unset <vm_id> DEBUG

​
Reconnect to an existing VM

You can also reconnect to a running VM by its ID: 
from smolvm import SmolVM

# Reconnect to an existing VM
vm = SmolVM.from_id("vm-abcdef12")
print(f"Status: {vm.status}")

​
Disk isolation defaults

SmolVM now defaults to isolated per-VM disks (disk_mode="isolated"), so each VM gets its own writable rootfs clone (sandbox-by-default). If you intentionally want shared/persistent image behavior across VMs, set: 
from smolvm import VMConfig

config = VMConfig(..., disk_mode="shared")