内容摘录
<div align="center">
<img src="docs/assets/logo.svg" alt="OpenSandbox logo" width="150" />
<h1>OpenSandbox</h1>
<p align="center">
<a href="https://github.com/alibaba/OpenSandbox">
<img src="https://img.shields.io/github/stars/alibaba/OpenSandbox.svg?style=social" alt="GitHub stars" />
</a>
<a href="https://deepwiki.com/alibaba/OpenSandbox">
<img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" />
</a>
<a href="https://www.apache.org/licenses/LICENSE-2.0.html">
<img src="https://img.shields.io/github/license/alibaba/OpenSandbox.svg" alt="license" />
</a>
<a href="https://badge.fury.io/py/opensandbox">
<img src="https://badge.fury.io/py/opensandbox.svg" alt="PyPI version" />
</a>
<a href="https://badge.fury.io/js/@alibaba-group%2Fopensandbox">
<img src="https://badge.fury.io/js/@alibaba-group%2Fopensandbox.svg" alt="npm version" />
</a>
<a href="https://github.com/alibaba/OpenSandbox/actions">
<img src="https://github.com/alibaba/OpenSandbox/actions/workflows/real-e2e.yml/badge.svg?branch=main" alt="E2E Status" />
</a>
</p>
<hr />
</div>
English | 中文
OpenSandbox is a **general-purpose sandbox platform** for AI applications, offering multi-language SDKs, unified sandbox APIs, and Docker/Kubernetes runtimes for scenarios like Coding Agents, GUI Agents, Agent Evaluation, AI Code Execution, and RL Training.
Features
**Multi-language SDKs**: Client SDKs for Python, Java/Kotlin, and JavaScript/TypeScript.
**Sandbox Protocol**: Defines sandbox lifecycle management APIs and sandbox execution APIs so you can extend custom sandbox runtimes.
**Sandbox Runtime**: Built-in lifecycle management supporting Docker and high-performance Kubernetes runtime, enabling both local runs and large-scale distributed scheduling.
**Sandbox Environments**: Built-in Command, Filesystem, and Code Interpreter implementations. Examples cover Coding Agents (e.g., Claude Code), browser automation (Chrome, Playwright), and desktop environments (VNC, VS Code).
**Network Policy**: Unified Ingress Gateway with multiple routing strategies plus per-sandbox egress controls.
Examples
Basic Sandbox Operations
Requirements:
Docker (required for local execution)
Python 3.10+ (recommended for examples and local runtime)
Install and Configure the Sandbox Server
If you prefer working from source, you can still clone the repo for development, but server startup no longer requires it.
Start the Sandbox Server
Create a Code Interpreter and Execute Commands
Install the Code Interpreter SDK
Create a sandbox and execute commands
More Examples
OpenSandbox provides rich examples demonstrating sandbox usage in different scenarios. All example code is located in the examples/ directory.
🎯 Basic Examples
**code-interpreter** - End-to-end Code Interpreter SDK workflow in a sandbox.
**aio-sandbox** - All-in-One sandbox setup using the OpenSandbox SDK.
**agent-sandbox** - Run OpenSandbox on Kubernetes via kubernetes-sigs/agent-sandbox.
🤖 Coding Agent Integrations
**claude-code** - Run Claude Code inside OpenSandbox.
**gemini-cli** - Run Google Gemini CLI inside OpenSandbox.
**codex-cli** - Run OpenAI Codex CLI inside OpenSandbox.
**iflow-cli** - Run iFLow CLI inside OpenSandbox.
**langgraph** - LangGraph state-machine workflow that creates/runs a sandbox job with fallback retry.
**google-adk** - Google ADK agent using OpenSandbox tools to write/read files and run commands.
**openclaw** - Launch an OpenClaw Gateway inside a sandbox.
🌐 Browser and Desktop Environments
**chrome** - Headless Chromium with VNC and DevTools access for automation/debugging.
**playwright** - Playwright + Chromium headless scraping and testing example.
**desktop** - Full desktop environment in a sandbox with VNC access.
**vscode** - code-server (VS Code Web) running inside a sandbox for remote dev.
🧠 ML and Training
**rl-training** - DQN CartPole training in a sandbox with checkpoints and summary output.
For more details, please refer to examples and the README files in each example directory.
Project Structure
| Directory | Description |
|-----------|------------------------------------------------------------------|
| sdks/ | Multi-language SDKs (Python, Java/Kotlin, TypeScript/JavaScript) |
| specs/ | OpenAPI specs and lifecycle specifications |
| server/ | Python FastAPI sandbox lifecycle server |
| kubernetes/ | Kubernetes deployment and examples |
| components/execd/ | Sandbox execution daemon (commands and file operations) |
| components/ingress/ | Sandbox traffic ingress proxy |
| components/egress/ | Sandbox network egress control |
| sandboxes/ | Runtime sandbox implementations |
| examples/ | Integration examples and use cases |
| oseps/ | OpenSandbox Enhancement Proposals |
| docs/ | Architecture and design documentation |
| tests/ | Cross-component E2E tests |
| scripts/ | Development and maintenance scripts |
For detailed architecture, see docs/architecture.md.
Documentation
docs/architecture.md – Overall architecture & design philosophy
SDK
Sandbox base SDK (Java\Kotlin SDK, Python SDK, JavaScript/TypeScript SDK) - includes sandbox lifecycle, command execution, file operations
Code Interpreter SDK (Java\Kotlin SDK, Python SDK, JavaScript/TypeScript SDK) - code interpreter
specs/README.md - OpenAPI definitions for sandbox lifecycle API and sandbox execution API
server/README.md - Sandbox server startup and configuration; supports Docker and Kubernetes runtimes
License
This project is open source under the Apache 2.0 License.
Roadmap
SDK
[ ] **Go SDK** - Go client SDK for sandbox lifecycle management, command execution, and file operations.
Sandbox Runtime
[ ] **Persistent storage** - Mountable persistent storage for sandboxes (see Proposal 0003).
[ ] **Ingress multi-network strategies** - Multi-Kubernetes provisioning and multi-network modes for the Ingress Gateway.
[ ] **Local lightweight sandbox** - Lightweight sandbox for AI tools running directly on PCs.
Deployment
[ ] **Kubernetes Helm** - Helm charts to deploy all …