Content
[中文](README.zh-CN.md)
# MimoBox
[](https://github.com/showkw/mimobox/actions/workflows/ci.yml) [](LICENSE-MIT) [](https://pypi.org/project/mimobox/) []()
**Run AI-generated code safely, locally, and instantly.**
No API keys. No Docker. No cloud.
MimoBox is a local sandbox runtime for AI agents. It provides multi-layer isolation — OS (Landlock + Seccomp), WebAssembly (Wasmtime), and microVM (KVM) — through a unified SDK, CLI, MCP server, and Python binding. Download a single binary and start executing code safely.
---
## Why MimoBox?
- **Local-first** — Runs entirely on your machine. No data leaves your network, no API keys required.
- **Multi-layer isolation** — OS-level (Landlock + Seccomp + Namespaces), Wasm (Wasmtime), and microVM (KVM) backends with smart auto-routing.
- **Ultra-low latency** — OS cold start P50 8.24 ms, Wasm cold start P50 1.01 ms, warm pool acquire P50 0.19 µs.
- **Agent-native** — MCP server with 15 tools, Python SDK, LangChain / OpenAI Agents SDK integration out of the box.
See [Performance](#performance) for detailed benchmarks across all isolation layers.
## Features
- **Multi-layer isolation** — OS (Landlock + Seccomp + Namespaces), Wasm (Wasmtime), and microVM (KVM) with smart auto-routing
- **Sandbox Registry** — `Sandbox.list()` to track all active instances, `Sandbox.id` for unique identification
- **Persistent Env Vars** — Set environment variables at sandbox creation via `env_vars`, applied to every command
- **Runtime Metrics** — Monitor CPU, memory, I/O, and Wasm fuel per sandbox with `Sandbox.metrics()`
- **MCP Server** — 15 tools for AI agent integration, including file management and HTTP ACL
- **Ultra-low latency** — OS cold start P50 8.24 ms, Wasm cold start P50 1.01 ms, warm pool acquire P50 0.19 us
## Quick Start
### Install
```bash
curl -fsSL https://raw.githubusercontent.com/showkw/mimobox/master/scripts/install.sh | bash
```
### Try it
```bash
mimobox run --backend auto --command "/bin/echo hello from MimoBox!"
```
That's it -- no API keys, no Docker, no cloud. The `auto` backend picks the best isolation layer for your platform.
### Python
```python
from mimobox import Sandbox
# Create a sandbox with default settings
with Sandbox() as sb:
# Execute a command safely
result = sb.execute("echo 'Hello from sandbox!'")
print(result.stdout)
# The sandbox isolates the process:
# - Filesystem access is restricted
# - Network access is blocked by default
# - Resource limits are enforced
```
### Rust
```toml
[dependencies]
mimobox-sdk = "0.1.0-alpha"
```
### MCP Server (Linux only)
Install the MCP server binary:
```bash
# Option 1: Install together with CLI
curl -fsSL https://raw.githubusercontent.com/showkw/mimobox/master/scripts/install.sh | bash -s -- --with-mcp
# Option 2: Download separately
curl -fsSL https://github.com/showkw/mimobox/releases/latest/download/mimobox-mcp-$(uname -s)-$(uname -m) -o /usr/local/bin/mimobox-mcp
chmod +x /usr/local/bin/mimobox-mcp
```
```bash
mimobox-mcp # stdio mode (default)
mimobox-mcp --transport http --port 8080 # Streamable HTTP mode
```
Add to your MCP client config:
```json
{
"mcpServers": {
"mimobox": {
"command": "mimobox-mcp"
}
}
}
```
## Integration Examples
### LangChain
```python
from mimobox import Sandbox
from langchain_core.tools import tool
@tool
def sandbox_run_command(command: str) -> str:
"""Run a command inside a secure sandbox."""
with Sandbox() as sb:
return sb.execute(command).stdout
```
### OpenAI Agents SDK
```python
from mimobox import Sandbox
from agents import function_tool
@function_tool
def sandbox_execute(command: str) -> str:
"""Run a command inside a secure sandbox."""
with Sandbox() as sb:
return sb.execute(command).stdout
```
### Python SDK
```python
from mimobox import Sandbox
with Sandbox() as sb:
# Untrusted code runs safely -- network is denied by default
result = sb.execute("curl https://example.com")
print(result) # Command fails: network access denied
# Filesystem writes outside the sandbox temp dir are blocked
result = sb.execute("touch /outside_sandbox.txt")
print(result) # Command fails: write access denied
```
```python
# File API (requires Linux + KVM / microVM backend)
with Sandbox() as sandbox:
sandbox.write_file("/tmp/hello.py", b"print('hello')")
result = sandbox.execute("python3 /tmp/hello.py")
entries = sandbox.list_dir("/tmp")
```
## Platform Support
| Platform | OS Sandbox | Wasm Sandbox | microVM Sandbox |
| --- | --- | --- | --- |
| Linux (x86_64) | Landlock + Seccomp + Namespaces | Wasmtime | KVM (requires `/dev/kvm` + guest assets) |
| macOS (ARM64, Intel) | Seatbelt | Wasmtime | Not available |
> **Note for macOS users**: macOS currently supports OS-level isolation (Seatbelt) only. Wasm, microVM, MCP Server, streaming execution, file operations, and HTTP proxy require Linux. See [Platform Support](#platform-support) for details.
## Isolation Layers
| Layer | Backend | Best For |
| --- | --- | --- |
| OS-level | Linux Landlock + Seccomp + Namespaces; macOS Seatbelt | Fast local commands, default smart routing |
| Wasm | Wasmtime + WASI | Deterministic portable workloads |
| microVM | Linux KVM + guest protocol + pools + snapshot/fork | Strong isolation, production workloads |
## Performance
| Metric | P50 |
| --- | ---:|
| OS cold start | 8.24 ms |
| Wasm cold start | 1.01 ms |
| Warm pool acquire | 0.19 µs |
| microVM cold start | 253 ms |
| microVM snapshot restore (pooled) | 28 ms |
> **Status**: MimoBox is in **alpha** (v0.1.x). It has not undergone a formal security audit. See [SECURITY.md](SECURITY.md) for threat model and known limitations.
## Documentation
- [Getting Started](docs/getting-started.md) — Installation, CLI usage, and SDK examples
- [Architecture](docs/architecture.md) — Workspace structure and smart routing
- [API Reference](docs/api.md) — Rust SDK types and methods
- [Python SDK](docs/python-sdk.md) — Python binding installation and usage
- [MCP Server](docs/mcp-server.md) — Tool reference and client integration
- [MCP Configuration](docs/mcp-config.md) — Templates for Claude Desktop, Cursor, VS Code
- [Performance](docs/performance.md) — Benchmark methodology and detailed metrics
- [FAQ & Troubleshooting](docs/faq.md) — Common issues and solutions
## License
Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or [MIT license](LICENSE-MIT) at your option.
