OpenSandbox

Documentation | 中文文档

OpenSandbox 是一个面向 AI 应用的通用沙箱平台，提供多语言 SDK、统一的沙箱 API 以及适用于 Docker/Kubernetes 的运行时。它适用于编码智能体（Coding Agents）、图形界面智能体（GUI Agents）、智能体评估、AI 代码执行以及强化学习（RL）训练等场景。

OpenSandbox 现已列入 CNCF Landscape。

特性

• 多语言 SDK：提供 Python、Java/Kotlin、JavaScript/TypeScript、C#/.NET 和 Go 语言的沙箱 SDK。
• 沙箱协议：定义了沙箱生命周期管理 API 和沙箱执行 API，方便用户扩展自定义的沙箱运行时。
• 沙箱运行时：内置生命周期管理，支持 Docker 和高性能 Kubernetes 运行时，支持本地运行及大规模分布式调度。
• 沙箱环境：内置命令、文件系统和代码解释器实现。示例涵盖了编码智能体（如 Claude Code）、浏览器自动化（Chrome、Playwright）和桌面环境（VNC、VS Code）。
• 网络策略：统一的 Ingress Gateway 提供多种路由策略，以及针对每个沙箱的 egress 控制。
• 强隔离：支持如 gVisor、Kata Containers 和 Firecracker 微虚拟机（microVM）等安全容器运行时，以增强沙箱工作负载与宿主机之间的隔离性。详情请参考 安全容器运行时指南。

SDK

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 工具，用于处理常见的沙箱工作流：创建沙箱、执行命令、移动文件、检查诊断信息以及管理运行时 egress 策略。

安装：

pip install opensandbox-cli
# 或
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 
osb sandbox create --image python:3.12 --timeout 30m -o json
osb command run  -o raw -- python -c "print(1 + 1)"

请查看 CLI README 获取完整的命令参考。

MCP

OpenSandbox MCP 服务器向支持 MCP 的客户端（如 Claude Code 和 Cursor）暴露了沙箱创建、命令执行和文本文件操作等功能。

安装并运行：

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+（示例和本地运行时必需）

安装并配置沙箱服务器

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

uvx opensandbox-server

# 显示帮助
# uvx opensandbox-server -h

创建代码解释器并执行命令/代码

安装代码解释器 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. 创建沙箱
    sandbox = await Sandbox.create(
        "opensandbox/code-interpreter:v1.0.2",
        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
        env={"PYTHON_VERSION": "3.11"},
        timeout=timedelta(minutes=10),
    )

    async with sandbox:

        # 2. 执行 shell 命令
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. 写入文件
        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
        ])

        # 4. 读取文件
        content = await sandbox.files.read_file("/tmp/hello.txt")
        print(f"Content: {content}") # Content: Hello World

        # 5. 创建代码解释器
        interpreter = await CodeInterpreter.create(sandbox)