README_zh.md
1 <div align="center"> 2 <img src="assets/logo.svg" alt="OpenSandbox logo" width="150" /> 3 4 <h1>OpenSandbox</h1> 5 6 <p align="center"> 7 <a href="https://github.com/alibaba/OpenSandbox"> 8 <img src="https://img.shields.io/github/stars/alibaba/OpenSandbox.svg?style=social" alt="GitHub stars" /> 9 </a> 10 <a href="https://deepwiki.com/alibaba/OpenSandbox"> 11 <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" /> 12 </a> 13 <a href="https://www.apache.org/licenses/LICENSE-2.0.html"> 14 <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="license" /> 15 </a> 16 <a href="https://badge.fury.io/py/opensandbox"> 17 <img src="https://badge.fury.io/py/opensandbox.svg" alt="PyPI version" /> 18 </a> 19 <a href="https://badge.fury.io/js/@alibaba-group%2Fopensandbox"> 20 <img src="https://badge.fury.io/js/@alibaba-group%2Fopensandbox.svg" alt="npm version" /> 21 </a> 22 <a href="https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox"> 23 <img src="https://img.shields.io/badge/CNCF-Landscape-0C66E4" alt="CNCF Landscape" /> 24 </a> 25 <a href="https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=&_dt_no_comment=1&origin=11"> 26 <img src="https://img.shields.io/badge/DingTalk-Join-0089FF?logo=dingtalk&logoColor=white" alt="DingTalk" /> 27 </a> 28 <a href="https://github.com/alibaba/OpenSandbox/actions"> 29 <img src="https://github.com/alibaba/OpenSandbox/actions/workflows/real-e2e.yml/badge.svg?branch=main" alt="E2E Status" /> 30 </a> 31 <a href="https://github.com/alibaba/OpenSandbox/actions"> 32 <img src="https://github.com/alibaba/OpenSandbox/actions/workflows/kubernetes-nightly-build.yml/badge.svg?branch=main" alt="E2E Status" /> 33 </a> 34 </p> 35 36 <hr /> 37 </div> 38 39 中文 | [English](../README.md) 40 41 OpenSandbox 是一个面向 AI 应用的**通用沙箱平台**，提供多语言 SDK、统一的沙箱 API，以及 Docker/Kubernetes 运行时，适用于 Coding Agent、GUI Agent、Agent 评测、AI 代码执行和强化学习训练等场景。 42 43 OpenSandbox 已进入 [CNCF Landscape](https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox)。 44 45 ## 核心特性 46 47 - **多语言 SDK**：提供 Python、Java/Kotlin、JavaScript/TypeScript、C#/.NET、Go 的沙箱 SDK。 48 - **沙箱协议**：定义了沙箱生命周期管理 API 和沙箱执行 API。你可以通过这些沙箱协议扩展自己的沙箱运行时。 49 - **沙箱运行时**：沙箱全生命周期管理，支持 Docker 和[自研高性能 Kubernetes 运行时](../kubernetes)，实现本地运行、企业级大规模分布式沙箱调度。 50 - **沙箱环境**：内置 Command、Filesystem、Code Interpreter 实现。并提供 Coding Agent（Claude Code 等）、浏览器自动化（Chrome、Playwright）和桌面环境（VNC、VS Code）等示例。 51 - **网络策略**：提供统一的 [Ingress Gateway](../components/ingress) 实现，并支持多种路由策略；提供单实例级别的沙箱[出口网络限制](../components/egress)。 52 - **强隔离安全**：支持 gVisor、Kata Containers 和 Firecracker 微虚拟机等安全容器运行时，为沙箱工作负载与宿主机之间提供增强的安全隔离。详见 [安全容器运行时指南](secure-container.md)。 53 54 ## SDKs 55 56 Python: 57 58 ```bash 59 pip install opensandbox 60 ``` 61 62 Java/Kotlin (Gradle Kotlin DSL): 63 64 ```kotlin 65 dependencies { 66 implementation("com.alibaba.opensandbox:sandbox:{latest_version}") 67 } 68 ``` 69 70 Java/Kotlin (Maven): 71 72 ```xml 73 <dependency> 74 <groupId>com.alibaba.opensandbox</groupId> 75 <artifactId>sandbox</artifactId> 76 <version>{latest_version}</version> 77 </dependency> 78 ``` 79 80 JavaScript/TypeScript: 81 82 ```bash 83 npm install @alibaba-group/opensandbox 84 ``` 85 86 C#/.NET: 87 88 ```bash 89 dotnet add package Alibaba.OpenSandbox 90 ``` 91 92 Go: 93 94 ```bash 95 go get github.com/alibaba/OpenSandbox/sdks/sandbox/go 96 ``` 97 98 ## 快速开始 99 100 环境要求： 101 102 - Docker（本地运行必需） 103 - Python 3.10+（示例和本地运行所需） 104 105 ### 安装并配置 Sandbox Server 106 107 ```bash 108 uvx opensandbox-server init-config ~/.sandbox.toml --example docker 109 110 uvx opensandbox-server 111 112 # 查看帮助 113 # uvx opensandbox-server -h 114 ``` 115 116 ### 创建 Code Interpreter 并执行命令/代码 117 118 安装 Code Interpreter SDK 119 120 ```bash 121 uv pip install opensandbox-code-interpreter 122 ``` 123 124 创建沙箱并执行命令 125 126 ```python 127 import asyncio 128 from datetime import timedelta 129 130 from code_interpreter import CodeInterpreter, SupportedLanguage 131 from opensandbox import Sandbox 132 from opensandbox.models import WriteEntry 133 134 async def main() -> None: 135 # 1. Create a sandbox 136 sandbox = await Sandbox.create( 137 "sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2", 138 entrypoint=["/opt/opensandbox/code-interpreter.sh"], 139 env={"PYTHON_VERSION": "3.11"}, 140 timeout=timedelta(minutes=10), 141 ) 142 143 async with sandbox: 144 145 # 2. Execute a shell command 146 execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'") 147 print(execution.logs.stdout[0].text) 148 149 # 3. Write a file 150 await sandbox.files.write_files([ 151 WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644) 152 ]) 153 154 # 4. Read a file 155 content = await sandbox.files.read_file("/tmp/hello.txt") 156 print(f"Content: {content}") # Content: Hello World 157 158 # 5. Create a code interpreter 159 interpreter = await CodeInterpreter.create(sandbox) 160 161 # 6. 执行 Python 代码（单次执行：直接传 language） 162 result = await interpreter.codes.run( 163 """ 164 import sys 165 print(sys.version) 166 result = 2 + 2 167 result 168 """, 169 language=SupportedLanguage.PYTHON, 170 ) 171 172 print(result.result[0].text) # 4 173 print(result.logs.stdout[0].text) # 3.11.14 174 175 # 7. Cleanup the sandbox 176 await sandbox.kill() 177 178 if __name__ == "__main__": 179 asyncio.run(main()) 180 ``` 181 182 ### 更多示例 183 184 OpenSandbox 提供了丰富的示例来演示不同场景下的沙箱使用方式。所有示例代码位于 `examples/` 目录下。 185 186 #### 🎯 基础示例 187 188 - **[code-interpreter](../examples/code-interpreter/README.md)** - Code Interpreter SDK 的端到端沙箱流程示例。 189 - **[aio-sandbox](../examples/aio-sandbox/README.md)** - 使用 OpenSandbox SDK 与 agent-sandbox 的一体化沙箱示例。 190 - **[agent-sandbox](../examples/agent-sandbox/README.md)** - 通过 [kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox) 在 Kubernetes 上运行 OpenSandbox。 191 - **卷存储** — [Docker PVC / 命名卷](../examples/docker-pvc-volume-mount/README.md)、[Docker OSSFS](../examples/docker-ossfs-volume-mount/README.md)、[Kubernetes PVC](../examples/kubernetes-pvc-volume-mount/README.md)：持久化与共享存储用法。 192 193 #### 🤖 Coding Agent 集成 194 195 - **Coding CLI** — [Claude Code](../examples/claude-code/README.md)、[Gemini CLI](../examples/gemini-cli/README.md)、[OpenAI Codex CLI](../examples/codex-cli/README.md)、[Qwen Code](../examples/qwen-code/README.md)、[Kimi CLI](../examples/kimi-cli/README.md)：在 OpenSandbox 中运行各厂商 CLI。 196 - **[langgraph](../examples/langgraph/README.md)** - 基于 LangGraph 状态机编排沙箱任务与回退重试。 197 - **[google-adk](../examples/google-adk/README.md)** - 使用 Google ADK 通过 OpenSandbox 工具读写文件并执行命令。 198 - **[openclaw](../examples/openclaw/README.md)** - 在沙箱中启动 OpenClaw Gateway。 199 200 #### 🌐 浏览器与桌面环境 201 202 - **[chrome](../examples/chrome/README.md)** - 带 VNC 与 DevTools 的无头 Chromium，用于自动化/调试。 203 - **[playwright](../examples/playwright/README.md)** - Playwright + Chromium 无头抓取与测试示例。 204 - **[desktop](../examples/desktop/README.md)** - 通过 VNC 访问的完整桌面环境沙箱。 205 - **[vscode](../examples/vscode/README.md)** - 在沙箱中运行 code-server（VS Code Web）进行远程开发。 206 207 #### 🧠 机器学习与训练 208 209 - **[rl-training](../examples/rl-training/README.md)** - 在沙箱中运行 DQN CartPole 训练，输出 checkpoint 与训练汇总。 210 211 更多详细信息请参考 [examples](../examples/README.md) 和各示例目录下的 README 文件。 212 213 ## 项目结构 214 215 | 目录 | 说明 | 216 |------|---------------------------------------------------| 217 | [`sdks/`](../sdks/) | 多语言 SDK（Python、Java/Kotlin、TypeScript/JavaScript、C#/.NET） | 218 | [`specs/`](../specs/) | OpenAPI 与生命周期规范 | 219 | [`server/`](../server/README_zh.md) | Python FastAPI 沙箱生命周期服务，并集成多种运行时实现 | 220 | [`kubernetes/`](../kubernetes/README-ZH.md) | Kubernetes 部署与示例 | 221 | [`components/execd/`](../components/execd/README_zh.md) | 沙箱执行守护进程，负责命令和文件操作 | 222 | [`components/ingress/`](../components/ingress/README.md) | 沙箱流量入口代理 | 223 | [`components/egress/`](../components/egress/README.md) | 沙箱网络 Egress 访问控制 | 224 | [`sandboxes/`](../sandboxes/) | 沙箱运行时实现与镜像（如 code-interpreter） | 225 | [`examples/`](../examples/README.md) | 集成示例和使用案例 | 226 | [`oseps/`](../oseps/README.md) | OpenSandbox Enhancement Proposals | 227 | [`docs/`](../docs/) | 架构和设计文档 | 228 | [`tests/`](../tests/) | 跨组件端到端测试 | 229 | [`scripts/`](../scripts/) | 开发和维护脚本 | 230 231 详细架构请参阅 [docs/architecture.md](architecture.md)。 232 233 ## 文档 234 235 - [docs/architecture.md](architecture.md) – 整体架构 & 设计理念 236 - [oseps/README.md](../oseps/README.md) – OpenSandbox 增强提案 (OSEPs) 237 - SDK 238 - Sandbox 基础 SDK（[Java\Kotlin SDK](../sdks/sandbox/kotlin/README_zh.md)、[Python SDK](../sdks/sandbox/python/README_zh.md)、[JavaScript/TypeScript SDK](../sdks/sandbox/javascript/README_zh.md)、[C#/.NET SDK](../sdks/sandbox/csharp/README_zh.md)）- 包含沙箱生命周期、命令执行、文件操作 239 - Code Interpreter SDK（[Java\Kotlin SDK](../sdks/code-interpreter/kotlin/README_zh.md) 、[Python SDK](../sdks/code-interpreter/python/README_zh.md)、[JavaScript/TypeScript SDK](../sdks/code-interpreter/javascript/README_zh.md)、[C#/.NET SDK](../sdks/code-interpreter/csharp/README_zh.md)）- 代码解释器 240 - [specs/README.md](../specs/README_zh.md) - 包含沙箱生命周期 API 和沙箱执行 API 的 OpenAPI 定义 241 - [server/README.md](../server/README_zh.md) - 包含沙箱 Server 的启动和配置，支持 Docker 与 Kubernetes Runtime 242 243 ## 许可证 244 245 本项目采用 [Apache 2.0 License](../LICENSE) 开源。 246 247 你可以在遵守许可条款的前提下，将 OpenSandbox 用于个人或商业项目。 248 249 ## 路线图 [2026.03] 250 251 ### SDK 252 253 - **沙箱客户端连接池** - 客户端沙箱连接池管理，提供预配置的沙箱实例，以毫秒级速度获取沙箱环境。 254 - **Go SDK** - Go 客户端 SDK，用于沙箱生命周期管理、命令执行和文件操作。 255 256 ### Sandbox Runtime 257 258 - **持久化存储** - 沙箱的持久化存储挂载（参见 [Proposal 0003](../oseps/0003-volume-and-volumebinding-support.md)）。 259 - **本地轻量级沙箱** - 为运行在 PC 上的 AI 工具提供轻量级沙箱。 260 - **安全容器** - 为在容器内运行的 AI Agent 提供安全沙箱。 261 262 ### Deployment 263 264 - **部署指南** - 自托管 Kubernetes 集群的部署指南。 265 266 ## 联系与讨论 267 268 - Issue：通过 GitHub Issues 提交 bug、功能请求或设计讨论 269 - 钉钉群：加入 [OpenSandbox 技术交流群](https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=&_dt_no_comment=1&origin=11) 270 271 欢迎一起把 OpenSandbox 打造成 AI 场景下的通用沙箱基础设施。 272 273 ## Star History 274 275 [](https://www.star-history.com/#alibaba/OpenSandbox&type=date&legend=top-left)