wehub-resource-sync
25e728f4ae
Real E2E Tests / changes (push) Successful in 2m18s
Real E2E Tests / JavaScript E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / C# E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Python E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Java E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Go E2E (docker bridge) (push) Has been cancelled
Deploy Docs Pages / build (push) Has been cancelled
Deploy Docs Pages / deploy (push) Has been cancelled
Real E2E Tests / Real E2E CI (push) Has been cancelled
306 lines
14 KiB
Markdown
306 lines
14 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/opensandbox-group/OpenSandbox) · [上游 README](https://github.com/opensandbox-group/OpenSandbox/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center">
|
||
<img src="docs/public/images/logo.svg" alt="OpenSandbox logo" width="150" />
|
||
|
||
<h1>OpenSandbox</h1>
|
||
|
||
<p align="center">
|
||
<a href="https://trendshift.io/repositories/21828" target="_blank"><img src="https://trendshift.io/api/badge/repositories/21828" alt="opensandbox-group%2FOpenSandbox | Trendshift" style="width: 320px; height: 70px;" width="320" height="70" /></a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://github.com/opensandbox-group/OpenSandbox"><img src="https://img.shields.io/github/stars/opensandbox-group/OpenSandbox?style=flat-square&logo=github&logoColor=white&label=Stars&color=181717" alt="Stars" /></a>
|
||
<a href="https://www.bestpractices.dev/projects/12588"><img src="https://img.shields.io/badge/OpenSSF-Best-4C566A?style=flat-square" alt="OpenSSF Best Practices" /></a>
|
||
<a href="https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox"><img src="https://img.shields.io/badge/CNCF-Landscape-0C66E4?style=flat-square" alt="CNCF Landscape" /></a>
|
||
<a href="https://discord.gg/g7FuPs8YeD"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord" /></a>
|
||
<a href="https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=&_dt_no_comment=1&origin=11"><img src="https://img.shields.io/badge/DingTalk-Join-0089FF?style=flat-square" alt="DingTalk" /></a>
|
||
<a href="https://github.com/opensandbox-group/OpenSandbox/actions"><img src="https://img.shields.io/github/actions/workflow/status/opensandbox-group/OpenSandbox/real-e2e.yml?branch=main&label=TEST&style=flat-square&logo=github&logoColor=white" alt="E2E Status" /></a>
|
||
<a href="https://github.com/opensandbox-group/OpenSandbox/actions"><img src="https://img.shields.io/github/actions/workflow/status/opensandbox-group/OpenSandbox/kubernetes-nightly-build.yml?branch=main&label=K8S&style=flat-square&logo=kubernetes&logoColor=white" alt="Kubernetes nightly build status" /></a>
|
||
</p>
|
||
|
||
<hr />
|
||
</div>
|
||
|
||
OpenSandbox 是一个面向 AI 应用的**通用沙箱平台（general-purpose sandbox platform）**，提供多语言 SDK、统一的沙箱 API，以及适用于 Coding Agents、GUI Agents、Agent Evaluation、AI Code Execution、RL Training 等场景的 Docker/Kubernetes 运行时。
|
||
|
||
## 特性
|
||
|
||
- 🧩 **SDK、CLI 与 MCP**：提供多语言 SDK、osb CLI 以及 MCP 服务器集成，用于创建沙箱、执行命令和文件操作。请参阅 [SDK](#sdks)、[CLI](#cli) 和 [MCP](#mcp)。
|
||
- 📜 **沙箱协议（Sandbox Protocol）**：定义沙箱生命周期管理 API 与沙箱执行 API，便于扩展自定义沙箱运行时。请参阅 [API 规范](specs/README.md)。
|
||
- 🚀 **沙箱运行时（Sandbox Runtime）**：内置生命周期管理，支持 Docker 及高性能 Kubernetes 运行时，既可本地运行，也可大规模分布式调度。请参阅 [Kubernetes 运行时](./kubernetes)。
|
||
- 🖥️ **沙箱环境（Sandbox Environments）**：内置 Command、Filesystem 与 Code Interpreter 实现。示例涵盖 Coding Agents（如 Claude Code）、浏览器自动化（Chrome、Playwright）以及桌面环境（VNC、VS Code）。
|
||
- 🚦 **网络策略（Network Policy）**：统一的入口网关，支持多种路由策略，并提供按沙箱粒度的出口（egress）控制。请参阅 [Ingress Gateway](components/ingress) 和 [egress 控制](components/egress)。
|
||
- 🔑 **凭证保险库（Credential Vault）**：为沙箱出站请求安全注入凭证，避免向工作负载暴露真实密钥。请参阅 [Credential Vault](docs/guides/credential-vault.md)。
|
||
- 🏰 **强隔离（Strong Isolation）**：支持 gVisor、Kata Containers、Firecracker microVM 等安全容器运行时，增强沙箱工作负载与宿主机之间的隔离。详情请参阅 [安全容器运行时指南](docs/guides/secure-container.md)。
|
||
|
||
## SDKs
|
||
|
||
Python:
|
||
|
||
```bash
|
||
pip install opensandbox
|
||
```
|
||
|
||
Java/Kotlin (Gradle Kotlin DSL):
|
||
|
||
```kotlin
|
||
dependencies {
|
||
implementation("com.alibaba.opensandbox:sandbox:{latest_version}")
|
||
}
|
||
```
|
||
|
||
Java/Kotlin (Maven):
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.alibaba.opensandbox</groupId>
|
||
<artifactId>sandbox</artifactId>
|
||
<version>{latest_version}</version>
|
||
</dependency>
|
||
```
|
||
|
||
JavaScript/TypeScript:
|
||
|
||
```bash
|
||
npm install @alibaba-group/opensandbox
|
||
```
|
||
|
||
C#/.NET:
|
||
|
||
```bash
|
||
dotnet add package Alibaba.OpenSandbox
|
||
```
|
||
|
||
Go:
|
||
|
||
```bash
|
||
go get github.com/alibaba/OpenSandbox/sdks/sandbox/go
|
||
```
|
||
|
||
## CLI
|
||
|
||
OpenSandbox 还提供 `osb`，一款用于常见沙箱工作流的终端 CLI：创建沙箱、运行命令、移动文件、查看诊断信息以及管理运行时出口策略。
|
||
|
||
安装：
|
||
|
||
```bash
|
||
pip install opensandbox-cli
|
||
# or
|
||
uv tool install opensandbox-cli
|
||
```
|
||
|
||
快速开始：
|
||
|
||
```bash
|
||
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)"
|
||
```
|
||
|
||
完整命令参考请参阅 [CLI README](cli/README.md)。
|
||
|
||
## MCP
|
||
|
||
OpenSandbox MCP 服务器向 Claude Code、Cursor 等支持 MCP 的客户端暴露沙箱创建、命令执行以及文本文件操作能力。
|
||
|
||
安装并运行：
|
||
|
||
```bash
|
||
pip install opensandbox-mcp
|
||
opensandbox-mcp --domain localhost:8080 --protocol http
|
||
```
|
||
|
||
最小 stdio 配置：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"opensandbox": {
|
||
"command": "opensandbox-mcp",
|
||
"args": ["--domain", "localhost:8080", "--protocol", "http"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
各客户端的配置说明请参阅 [MCP README](sdks/mcp/sandbox/python/README.md)。
|
||
|
||
## 快速入门
|
||
|
||
环境要求：
|
||
|
||
- Docker（本地执行必需）
|
||
- Python 3.10+（示例与本地运行时必需）
|
||
|
||
### 安装并配置 Sandbox Server
|
||
|
||
```bash
|
||
uvx opensandbox-server init-config ~/.sandbox.toml --example docker
|
||
|
||
uvx opensandbox-server
|
||
|
||
# Show help
|
||
# uvx opensandbox-server -h
|
||
```
|
||
|
||
### 创建 Code Interpreter 并执行命令/代码
|
||
|
||
安装 Code Interpreter SDK
|
||
|
||
```bash
|
||
uv pip install opensandbox-code-interpreter
|
||
```
|
||
|
||
创建沙箱并执行命令与代码。
|
||
|
||
```python
|
||
import asyncio
|
||
from datetime import timedelta
|
||
|
||
from code_interpreter import CodeInterpreter, SupportedLanguage
|
||
from opensandbox import Sandbox
|
||
from opensandbox.models import WriteEntry
|
||
|
||
async def main() -> None:
|
||
# 1. Create a sandbox
|
||
sandbox = await Sandbox.create(
|
||
"opensandbox/code-interpreter:v1.1.0",
|
||
entrypoint=["/opt/code-interpreter/code-interpreter.sh"],
|
||
env={"PYTHON_VERSION": "3.11"},
|
||
timeout=timedelta(minutes=10),
|
||
)
|
||
|
||
async with sandbox:
|
||
|
||
# 2. Execute a shell command
|
||
execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
|
||
print(execution.logs.stdout[0].text)
|
||
|
||
# 3. Write a file
|
||
await sandbox.files.write_files([
|
||
WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
|
||
])
|
||
|
||
# 4. Read a file
|
||
content = await sandbox.files.read_file("/tmp/hello.txt")
|
||
print(f"Content: {content}") # Content: Hello World
|
||
|
||
# 5. Create a code interpreter
|
||
interpreter = await CodeInterpreter.create(sandbox)
|
||
|
||
# 6. Execute Python code (single-run, pass language directly)
|
||
result = await interpreter.codes.run(
|
||
"""
|
||
import sys
|
||
print(sys.version)
|
||
result = 2 + 2
|
||
result
|
||
""",
|
||
language=SupportedLanguage.PYTHON,
|
||
)
|
||
|
||
print(result.result[0].text) # 4
|
||
print(result.logs.stdout[0].text) # 3.11.14
|
||
|
||
# 7. Cleanup the sandbox
|
||
await sandbox.kill()
|
||
|
||
if __name__ == "__main__":
|
||
asyncio.run(main())
|
||
```
|
||
|
||
### 更多示例
|
||
|
||
OpenSandbox 提供涵盖 SDK 用法、智能体集成、浏览器自动化与训练工作负载的示例。所有示例代码位于 `examples/` 目录。
|
||
|
||
#### 🎯 基础示例
|
||
|
||
- **[code-interpreter](docs/examples/code-interpreter.md)** - 在沙箱中端到端演示 Code Interpreter SDK 工作流。
|
||
- **[aio-sandbox](docs/examples/aio-sandbox.md)** - 使用 OpenSandbox SDK 的一体化沙箱配置。
|
||
- **[agent-sandbox](docs/examples/agent-sandbox.md)** - 在 Kubernetes 上运行 OpenSandbox 工作负载的集成示例，配合 [kubernetes-sigs/agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox).
|
||
- **Volumes** — [Docker PVC / named volumes](docs/examples/docker-pvc-volume-mount.md)、[Docker OSSFS](docs/examples/docker-ossfs-volume-mount.md)、[Kubernetes PVC](docs/examples/kubernetes-pvc-volume-mount.md)：持久化与共享存储方案。
|
||
|
||
#### 🤖 编码智能体（Coding Agent）集成
|
||
|
||
- **Coding CLI** — [Claude Code](docs/examples/claude-code.md)、[Gemini CLI](docs/examples/gemini-cli.md)、[OpenAI Codex CLI](docs/examples/codex-cli.md)、[Qwen Code](docs/examples/qwen-code.md)、[Kimi CLI](docs/examples/kimi-cli.md)：在 OpenSandbox 内运行各厂商 CLI。
|
||
- **[langgraph](docs/examples/langgraph.md)** - 基于 LangGraph 的状态机工作流，用于创建/运行沙箱任务并支持失败重试（fallback retry）。
|
||
- **[google-adk](docs/examples/google-adk.md)** - 使用 OpenSandbox 工具进行文件读写与命令执行的 Google ADK 智能体。
|
||
- **[openclaw](docs/examples/openclaw.md)** - 在沙箱内启动 OpenClaw Gateway。
|
||
|
||
#### 🌐 浏览器与桌面环境
|
||
|
||
- **[chrome](docs/examples/chrome.md)** - 配备 VNC 与 DevTools 访问的 Chromium 沙箱，用于自动化与调试。
|
||
- **[playwright](docs/examples/playwright.md)** - Playwright + Chromium 无头（headless）爬取与测试示例。
|
||
- **[desktop](docs/examples/desktop.md)** - 带 VNC 访问的沙箱完整桌面环境。
|
||
- **[vscode](docs/examples/vscode.md)** - 在沙箱内运行 code-server（VS Code Web）以进行远程开发。
|
||
|
||
#### 🧠 训练与评估
|
||
|
||
- **[rl-training](docs/examples/rl-training.md)** - 在沙箱中进行 DQN CartPole 训练，含检查点与摘要输出。
|
||
- **[harbor-evaluation](docs/examples/harbor-evaluation.md)** - 在 OpenSandbox 上运行 [Harbor](https://github.com/harbor-framework/harbor) 智能体评估，每次试验使用一个沙箱。
|
||
|
||
更多详情请参阅[示例文档](docs/examples/index.md)。
|
||
|
||
## 项目结构
|
||
|
||
| 目录 | 说明 |
|
||
|-----------|------------------------------------------------------------------|
|
||
| [`sdks/`](sdks/) | 多语言 SDK（Python、Java/Kotlin、TypeScript/JavaScript、C#/.NET） |
|
||
| [`specs/`](specs/README.md) | OpenAPI 规范与生命周期（lifecycle）规范 |
|
||
| [`server/`](server/README.md) | Python FastAPI 沙箱生命周期服务器 |
|
||
| [`cli/`](cli/README.md) | OpenSandbox 命令行界面 |
|
||
| [`kubernetes/`](kubernetes/README.md) | Kubernetes 部署与示例 |
|
||
| [`components/execd/`](components/execd/README.md) | 沙箱执行守护进程（命令与文件操作） |
|
||
| [`components/ingress/`](components/ingress/README.md) | 沙箱流量入口代理 |
|
||
| [`components/egress/`](components/egress/README.md) | 沙箱网络出口控制 |
|
||
| [`sandboxes/`](sandboxes/) | 运行时沙箱实现 |
|
||
| [`examples/`](examples/) | 可运行的示例代码 |
|
||
| [`docs/examples/`](docs/examples/index.md) | 示例文档与用例 |
|
||
| [`oseps/`](oseps/README.md) | OpenSandbox Enhancement Proposals |
|
||
| [`docs/`](docs/) | 架构与设计文档 |
|
||
| [`tests/`](tests/) | 跨组件端到端（E2E）测试 |
|
||
| [`scripts/`](scripts/) | 开发与维护脚本 |
|
||
|
||
有关详细架构，请参阅[架构](docs/architecture/)。
|
||
|
||
## 文档
|
||
|
||
- [Architecture](docs/architecture/) – 整体架构与设计哲学
|
||
- [Credential Vault](docs/guides/credential-vault.md) - Credential Vault 凭据注入指南
|
||
- [Release Verification](docs/community/release-verification.md) - 发布签名与制品验证
|
||
- [oseps/README.md](oseps/README.md) – OpenSandbox Enhancement Proposals
|
||
- SDK
|
||
- 沙箱基础 SDK（[Java/Kotlin SDK](sdks/sandbox/kotlin/README.md)、[Python SDK](sdks/sandbox/python/README.md)、[JavaScript/TypeScript SDK](sdks/sandbox/javascript/README.md)、[C#/.NET SDK](sdks/sandbox/csharp/README.md)）、[Go SDK](sdks/sandbox/go/README.md) - 包含沙箱生命周期、命令执行、文件操作
|
||
- Code Interpreter SDK（[Java/Kotlin SDK](sdks/code-interpreter/kotlin/README.md)、[Python SDK](sdks/code-interpreter/python/README.md)、[JavaScript/TypeScript SDK](sdks/code-interpreter/javascript/README.md)、[C#/.NET SDK](sdks/code-interpreter/csharp/README.md)）- 代码解释器
|
||
- [cli/README.md](cli/README.md) - OpenSandbox CLI 安装与命令参考
|
||
- [sdks/mcp/sandbox/python/README.md](sdks/mcp/sandbox/python/README.md) - MCP 服务器安装与客户端配置
|
||
- [specs/README.md](specs/README.md) - 沙箱生命周期 API 与沙箱执行 API 的 OpenAPI 定义
|
||
- [server/README.md](server/README.md) - 沙箱服务器启动与配置；支持 Docker 与 Kubernetes 运行时
|
||
- [ROADMAP.md](ROADMAP.md) - 轻量级项目路线图与规划流程
|
||
|
||
## 许可证
|
||
|
||
本项目在 [Apache 2.0 License](LICENSE) 下开源。
|
||
|
||
## 路线图
|
||
|
||
当前项目路线图、规划范围以及路线图条目管理方式，请参阅 [ROADMAP.md](ROADMAP.md)。
|
||
|
||
## 联系与讨论
|
||
|
||
- Issues：通过 GitHub Issues 提交缺陷、功能请求或设计讨论
|
||
- Discord：加入 [OpenSandbox Discord 社区](https://discord.gg/g7FuPs8YeD)
|
||
- DingTalk：加入 [OpenSandbox 技术讨论群](https://qr.dingtalk.com/action/joingroup?code=v1,k1,A4Bgl5q1I1eNU/r33D18YFNrMY108aFF38V+r19RJOM=&_dt_no_comment=1&origin=11)
|
||
|
||
## Star 历史
|
||
|
||
[](https://www.star-history.com/#opensandbox-group/OpenSandbox&type=date&legend=top-left)
|