opensandbox-group--opensandbox/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

OpenSandbox

---

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、CLI 和 MCP。
• 📜 沙箱协议（Sandbox Protocol）：定义沙箱生命周期管理 API 与沙箱执行 API，便于扩展自定义沙箱运行时。请参阅 API 规范。
• 🚀 沙箱运行时（Sandbox Runtime）：内置生命周期管理，支持 Docker 及高性能 Kubernetes 运行时，既可本地运行，也可大规模分布式调度。请参阅 Kubernetes 运行时。
• 🖥️ 沙箱环境（Sandbox Environments）：内置 Command、Filesystem 与 Code Interpreter 实现。示例涵盖 Coding Agents（如 Claude Code）、浏览器自动化（Chrome、Playwright）以及桌面环境（VNC、VS Code）。
• 🚦 网络策略（Network Policy）：统一的入口网关，支持多种路由策略，并提供按沙箱粒度的出口（egress）控制。请参阅 Ingress Gateway 和 egress 控制。
• 🔑 凭证保险库（Credential Vault）：为沙箱出站请求安全注入凭证，避免向工作负载暴露真实密钥。请参阅 Credential Vault。
• 🏰 强隔离（Strong Isolation）：支持 gVisor、Kata Containers、Firecracker microVM 等安全容器运行时，增强沙箱工作负载与宿主机之间的隔离。详情请参阅 安全容器运行时指南。

SDKs

Python:

pip install opensandbox

Java/Kotlin (Gradle Kotlin DSL):

dependencies {
    implementation("com.alibaba.opensandbox:sandbox:{latest_version}")
}

Java/Kotlin (Maven):

<dependency>
    <groupId>com.alibaba.opensandbox</groupId>
    <artifactId>sandbox</artifactId>
    <version>{latest_version}</version>
</dependency>

JavaScript/TypeScript:

npm install @alibaba-group/opensandbox

C#/.NET:

dotnet add package Alibaba.OpenSandbox

Go:

go get github.com/alibaba/OpenSandbox/sdks/sandbox/go

CLI

OpenSandbox 还提供 osb，一款用于常见沙箱工作流的终端 CLI：创建沙箱、运行命令、移动文件、查看诊断信息以及管理运行时出口策略。

安装：

pip install opensandbox-cli
# or
uv tool install opensandbox-cli

快速开始：

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。

MCP

OpenSandbox MCP 服务器向 Claude Code、Cursor 等支持 MCP 的客户端暴露沙箱创建、命令执行以及文本文件操作能力。

安装并运行：

pip install opensandbox-mcp
opensandbox-mcp --domain localhost:8080 --protocol http

最小 stdio 配置：

{
  "mcpServers": {
    "opensandbox": {
      "command": "opensandbox-mcp",
      "args": ["--domain", "localhost:8080", "--protocol", "http"]
    }
  }
}

各客户端的配置说明请参阅 MCP README。

快速入门

环境要求：

• Docker（本地执行必需）
• Python 3.10+（示例与本地运行时必需）

安装并配置 Sandbox Server

uvx opensandbox-server init-config ~/.sandbox.toml --example docker

uvx opensandbox-server

# Show help
# uvx opensandbox-server -h

创建 Code Interpreter 并执行命令/代码

安装 Code Interpreter SDK

uv pip install opensandbox-code-interpreter

创建沙箱并执行命令与代码。

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 - 在沙箱中端到端演示 Code Interpreter SDK 工作流。
• aio-sandbox - 使用 OpenSandbox SDK 的一体化沙箱配置。
• agent-sandbox - 在 Kubernetes 上运行 OpenSandbox 工作负载的集成示例，配合 kubernetes-sigs/agent-sandbox.
• Volumes — Docker PVC / named volumes、Docker OSSFS、Kubernetes PVC：持久化与共享存储方案。

🤖 编码智能体（Coding Agent）集成

• Coding CLI — Claude Code、Gemini CLI、OpenAI Codex CLI、Qwen Code、Kimi CLI：在 OpenSandbox 内运行各厂商 CLI。
• langgraph - 基于 LangGraph 的状态机工作流，用于创建/运行沙箱任务并支持失败重试（fallback retry）。
• google-adk - 使用 OpenSandbox 工具进行文件读写与命令执行的 Google ADK 智能体。
• openclaw - 在沙箱内启动 OpenClaw Gateway。

🌐 浏览器与桌面环境

• chrome - 配备 VNC 与 DevTools 访问的 Chromium 沙箱，用于自动化与调试。
• playwright - Playwright + Chromium 无头（headless）爬取与测试示例。
• desktop - 带 VNC 访问的沙箱完整桌面环境。
• vscode - 在沙箱内运行 code-server（VS Code Web）以进行远程开发。

🧠 训练与评估

• rl-training - 在沙箱中进行 DQN CartPole 训练，含检查点与摘要输出。
• harbor-evaluation - 在 OpenSandbox 上运行 Harbor 智能体评估，每次试验使用一个沙箱。

更多详情请参阅示例文档。

项目结构

目录	说明
sdks/	多语言 SDK（Python、Java/Kotlin、TypeScript/JavaScript、C#/.NET）
specs/	OpenAPI 规范与生命周期（lifecycle）规范
server/	Python FastAPI 沙箱生命周期服务器
cli/	OpenSandbox 命令行界面
kubernetes/	Kubernetes 部署与示例
components/execd/	沙箱执行守护进程（命令与文件操作）
components/ingress/	沙箱流量入口代理
components/egress/	沙箱网络出口控制
sandboxes/	运行时沙箱实现
examples/	可运行的示例代码
docs/examples/	示例文档与用例
oseps/	OpenSandbox Enhancement Proposals
docs/	架构与设计文档
tests/	跨组件端到端（E2E）测试
scripts/	开发与维护脚本

有关详细架构，请参阅架构。

文档

• Architecture – 整体架构与设计哲学
• Credential Vault - Credential Vault 凭据注入指南
• Release Verification - 发布签名与制品验证
• oseps/README.md – OpenSandbox Enhancement Proposals
• SDK
  • 沙箱基础 SDK（Java/Kotlin SDK、Python SDK、JavaScript/TypeScript SDK、C#/.NET SDK）、Go SDK - 包含沙箱生命周期、命令执行、文件操作
  • Code Interpreter SDK（Java/Kotlin SDK、Python SDK、JavaScript/TypeScript SDK、C#/.NET SDK）- 代码解释器
• cli/README.md - OpenSandbox CLI 安装与命令参考
• sdks/mcp/sandbox/python/README.md - MCP 服务器安装与客户端配置
• specs/README.md - 沙箱生命周期 API 与沙箱执行 API 的 OpenAPI 定义
• server/README.md - 沙箱服务器启动与配置；支持 Docker 与 Kubernetes 运行时
• ROADMAP.md - 轻量级项目路线图与规划流程

许可证

本项目在 Apache 2.0 License 下开源。

路线图

当前项目路线图、规划范围以及路线图条目管理方式，请参阅 ROADMAP.md。

联系与讨论

• Issues：通过 GitHub Issues 提交缺陷、功能请求或设计讨论
• Discord：加入 OpenSandbox Discord 社区
• DingTalk：加入 OpenSandbox 技术讨论群

Star 历史