Run AI agents in sandboxes on your own infrastructure.
OpenSandbox gives AI applications isolated environments to execute code, run commands, manage files, and operate browsers or desktops. Start locally with Docker and deploy on Kubernetes through a unified sandbox API.
Quick Start · Examples · Documentation · Fast Sandbox
Features
| Feature | What it enables | Learn more |
|---|
| Fast Sandbox runtime | Fast, high-density sandboxes on Kubernetes. Firecracker creation: 64 ms P50 (serial) / 125.4 ms P99 (10 concurrent). Firecracker sandboxes support pause/resume with memory and disk state preserved. | Integration · Performance · Pause/resume |
| Agent working environments | Execute commands, manage files, and run code with built-in APIs. Integration examples show how to run coding agents, browsers, and desktops inside sandboxes. | Examples |
| Network access control | Route inbound traffic through a unified ingress gateway and control outbound access with per-sandbox egress policies. | Ingress · Egress |
| Credential Vault | Let agents call external services without exposing real credentials to sandbox workloads. | Credential Vault |
| Local to cluster | Start with Docker and deploy on Kubernetes through a unified lifecycle API. Resource pools and batch creation support agent evaluation and RL training workloads. | Kubernetes runtime |
| SDKs, CLI, and MCP | Integrate with Python, Java/Kotlin, TypeScript/JavaScript, C#/.NET, or Go SDKs. Use osb from the terminal or connect agents through MCP. | SDKs · CLI · MCP |
| Extensible sandbox protocol | Build custom runtime integrations against defined sandbox lifecycle and execution APIs. | API specs |
Getting Started
Requirements:
- Docker (required for local execution)
- Python 3.10+ (required for examples and local runtime)
Install and Configure the Sandbox Server
uvx opensandbox-server init-config ~/.sandbox.toml --example docker
uvx opensandbox-server
# Show help
# uvx opensandbox-server -h
Create a Sandbox and Execute Commands/Scripts
Install the Sandbox SDK
uv pip install opensandbox
Create a sandbox from an alpine image and execute commands and scripts.
import asyncio
from opensandbox import Sandbox
from opensandbox.models import WriteEntry
async def main() -> None:
# 1. Create a sandbox from the alpine image
sandbox = await Sandbox.create("alpine")
try:
# 2. Execute a shell command
execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
print(execution.logs.stdout[0].text)
# 3. Write a script file
await sandbox.files.write_files([
WriteEntry(
path="/tmp/hello.sh",
data="echo \"Hello $1\"\necho '2 + 2 =' $((2 + 2))",
mode=755,
)
])
# 4. Read the file back
content = await sandbox.files.read_file("/tmp/hello.sh")
print(f"Content: {content}")
# 5. Execute the script
execution = await sandbox.commands.run("sh /tmp/hello.sh OpenSandbox")
for log in execution.logs.stdout:
print(log.text)
finally:
# 6. Cleanup the sandbox
await sandbox.destroy()
if __name__ == "__main__":
asyncio.run(main())
Examples
Explore examples by what you want your agent to do. Runnable source code lives in examples/.
| Use case | What you can build | Examples |
|---|
| Coding agents | Run coding agents in isolated environments to edit files, execute commands, and complete development tasks. | Claude Code · Codex CLI · DeerFlow |
| Code execution and data analysis | Execute model-generated code and work with results through the Code Interpreter SDK. | Code Interpreter |
| Browser and desktop automation | Automate web interactions and testing, or give agents access to a desktop environment. | Playwright · Chrome · Desktop |
| Agent evaluation | Run evaluations with a separate sandbox for each trial. | Harbor Evaluation |
See the full example catalog for more coding agents, framework integrations, remote development environments, Kubernetes deployment, and storage patterns.
SDKs
Pick your language:
pip install opensandbox
dependencies {
implementation("com.alibaba.opensandbox:sandbox:{latest_version}")
}
<dependency>
<groupId>com.alibaba.opensandbox</groupId>
<artifactId>sandbox</artifactId>
<version>{latest_version}</version>
</dependency>
npm install @alibaba-group/opensandbox
dotnet add package Alibaba.OpenSandbox
go get github.com/alibaba/OpenSandbox/sdks/sandbox/go
CLI
OpenSandbox also provides osb, a terminal CLI for the common sandbox workflow: create sandboxes, run commands, move files, inspect diagnostics, and manage runtime egress policy.
Install:
pip install opensandbox-cli
# or
uv tool install opensandbox-cli
Quick start:
osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb config set connection.api_key <your-api-key>
osb sandbox create --image python:3.12 --timeout 30m -o json
osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"
See the CLI README for the full command reference.
MCP
The OpenSandbox MCP server exposes sandbox creation, command execution, and text file operations to MCP-capable clients such as Claude Code and Cursor.
Install and run:
pip install opensandbox-mcp
opensandbox-mcp --domain localhost:8080 --protocol http
Minimal stdio config:
{
"mcpServers": {
"opensandbox": {
"command": "opensandbox-mcp",
"args": ["--domain", "localhost:8080", "--protocol", "http"]
}
}
}
See the MCP README for client-specific setup.
Official Container Images
OpenSandbox release images are published under the same component name in three official registries:
- Docker Hub:
docker.io/opensandbox/<component>
- GitHub Container Registry:
ghcr.io/opensandbox-group/opensandbox/<component>
- Alibaba Cloud Container Registry:
sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/<component>
Tagged release images are signed keylessly with Cosign and include provenance attestations. Pin production images by digest and follow the release verification guide to verify the image against the OpenSandbox GitHub Actions identity before deployment.
Documentation
Contact and Discussion
About
OpenSandbox is a project of the Agentic AI Foundation (AAIF).
Licensed under the Apache 2.0 License.
