Metadata-Version: 2.4
Name: smolvm
Version: 0.0.6
Summary: Secure runtime for AI agents, and tools -- free and open-source from Celesto AI 🧡
Author-email: Celesto AI <hello@celesto.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.10
Requires-Dist: paramiko>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: requests-unixsocket>=0.3
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.115.0; extra == 'dashboard'
Requires-Dist: uvicorn[standard]>=0.34.0; extra == 'dashboard'
Requires-Dist: websockets>=14.0; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=4.2.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://ik.imagekit.io/gradsflow/celestoai/logo/smol-vm-logo_j3f2cqqRcO.png" width=100px>


# SmolVM

**Secure runtime for AI agents to execute untrusted code**

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

[Docs](https://docs.celesto.ai) • [Examples](examples/) • [Slack](https://join.slack.com/t/celestoai/shared_invite/zt-3qc7h8gno-Nb5_PElEWHDNnGqdVzC~4Q)

</div>

---

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

### 1. Prerequisites

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

### 2. Installation

First install the `smolvm` package which comes with a CLI.

```bash
# Install the Python package
pip install smolvm
```

SmolVM support Linux and macOS, depending on the system run one of the following commands for one time setup.

Linux (Firecracker):

```bash
sudo ./scripts/system-setup.sh --configure-runtime
```

MacOS (QEMU):

```bash
./scripts/system-setup-macos.sh
# Optional explicit backend override:
# export SMOLVM_BACKEND=qemu
```

## 3. Basic Usage

Use the default auto-configured, SSH-ready profile:


### 3.1 Using CLI

```bash
smolvm create --name "project-spacex"
smolvm ssh "project-spacex"
smolvm stop "project-spacex"

# Human-friendly Rich output by default
smolvm list

# Agent-friendly JSON envelope
smolvm create --name "project-spacex" --json
smolvm list --json
```


### 3.2 Using Python

```python
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:

```python
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)
```

## 4. Reconnect to an existing VM

You can also reconnect to a running VM by its ID:

```python
from smolvm import SmolVM

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

### 4.1 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:

```python
from smolvm import VMConfig

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

## 5. Port Forwarding

Expose a guest application to your local machine securely. `expose_local` prefers host-local nftables forwarding and automatically falls back to an SSH tunnel when needed.

```python
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}")
```

## 6. 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.

```python
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:

```bash
smolvm env set <vm_id> API_KEY=sk-... DEBUG=1
smolvm env list <vm_id> --show-values
smolvm env unset <vm_id> DEBUG

# Agent-friendly JSON output (values stay masked unless --show-values is added)
smolvm env list <vm_id> --json
```

## 7. Browser Sessions

SmolVM can now provision disposable Chromium sessions inside isolated VMs and expose:

- A localhost CDP endpoint for Playwright or other browser automation clients.
- An optional localhost noVNC live view for human takeover.
- Per-session artifacts for downloads, logs, and recordings.

CLI:

```bash
# Start a live browser session and print the CDP/live URLs
smolvm browser start --live --json

# List active browser sessions
smolvm browser list

# Open the live view in your default browser
smolvm browser open <session_id>

# Tail guest/browser logs
smolvm browser logs <session_id>

# Tear the session down and remove its persisted state
smolvm browser stop <session_id>
```

Python:

```python
from smolvm import BrowserSession, BrowserSessionConfig

with BrowserSession(
    BrowserSessionConfig(
        mode="live",
        record_video=True,
        viewport={"width": 1440, "height": 900},
    )
) as session:
    print(session.cdp_url)
    print(session.live_url)
```

Persistent browser profiles are also supported:

```python
from smolvm import BrowserSession, BrowserSessionConfig

session = BrowserSession(
    BrowserSessionConfig(
        profile_mode="persistent",
        profile_id="acct-1",
        mode="headless",
    )
)
session.start()
print(session.session_id, session.vm_id, session.cdp_url)
session.stop()
```

Diagnostics:

```bash
# Auto-detect backend (Darwin -> qemu, Linux -> firecracker)
smolvm doctor

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

# CI-friendly mode
smolvm doctor --json --strict
```

Cleanup:

```bash
# Human-friendly preview
smolvm cleanup --dry-run

# Agent-friendly JSON envelope
smolvm cleanup --json
```

Notes:

- Non-interactive commands default to Rich-rendered human output and support `--json` for agent workflows.
- `smolvm ssh` and `smolvm ui` remain human-only interactive flows.
- `--json` output now uses a shared envelope: `{ok, command, exit_code, data, error}`.

## Agent Framework Tool Examples

SmolVM can be wrapped as an agent tool or function in common Python agent frameworks.

- [Computer-use browser example](examples/agent_tools/computer_use_browser.py): let a model drive a real browser visually to answer a question on a site, with SmolVM handling isolation and live view.
- [LangChain `@tool` example](examples/agent_tools/langchain_tool.py): let a LangChain agent run shell commands in a safe sandbox.
- [OpenAI Agents SDK `@function_tool` example](examples/agent_tools/openai_agents_tool.py): let an OpenAI Agents SDK agent run shell commands in a safe sandbox.
- [PydanticAI `@agent.tool_plain` example](examples/agent_tools/pydanticai_tool.py): let a PydanticAI agent run shell commands in a safe sandbox; install `pydantic-ai`.
- [PydanticAI reusable sandbox example](examples/agent_tools/pydanticai_reusable_tool.py): keep one sandbox around across multiple PydanticAI runs; install `pydantic-ai`.

Before trying these scripts:

- Run `smolvm doctor` to confirm the local runtime is healthy.
- Set `OPENAI_API_KEY` and any optional model override env vars referenced in the example docstrings.

## ⚡ Performance

SmolVM is optimized for low-latency agent workflows. Latest lifecycle timings (p50) on a standard Linux host:

| Phase | Time |
|---|---|
| Create + Start | ~572ms |
| SSH ready | ~2.1s |
| Command execution | **~43ms** |
| Stop + Delete | ~751ms |
| **Full lifecycle (boot → run → teardown)** | **~3.5s** |

Run the benchmark yourself:

```bash
python scripts/benchmarks/bench_subprocess.py --vms 10 -v
```

> Measured on AMD Ryzen 7 7800X3D (8C/16T), Ubuntu Linux, KVM/Firecracker backend.

## 🔐 SSH trust model (important)

SmolVM currently prioritizes zero-touch VM access for local agent workflows.
By default, SSH host keys are not strictly verified during first connection
(`paramiko.AutoAddPolicy`).

- Use SmolVM on trusted/local networks and hosts.
- Do not expose guest SSH endpoints publicly without additional controls.
- See [SECURITY.md](SECURITY.md) for policy and scope details.

## 📄 License

Apache 2.0 License - see [LICENSE](LICENSE) for details.

---
<div align="center">
Built with 🧡 in London by <a href="https://celesto.ai">Celesto AI</a>
</div>
