OpenSandbox

英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

在您自己的基础设施上在沙箱中运行 AI 代理。

OpenSandbox 为 AI 应用程序提供隔离环境以执行代码、运行命令、管理文件，以及操作浏览器或桌面。可通过 Docker 在本地启动，并通过统一的沙箱 API 在 Kubernetes 上部署。

快速开始 · 示例 · 文档 · 快速沙箱

功能

入门

要求：

• Docker（本地执行所需）
• Python 3.10（示例和本地运行时所需）

安装并配置沙箱服务器

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

uvx opensandbox-server

# Show help
# uvx opensandbox-server -h

创建沙箱并执行命令/脚本

安装沙箱 SDK

uv pip install opensandbox

从 alpine 镜像创建一个沙箱并执行命令和脚本。

import asyncio

from opensandbox import Sandbox
from opensandbox.models import WriteEntry

async def main() -> None:
    # 1. Create a sandbox from the alpine image
    sandbox = await Sandbox.create("alpine")

    try:
        # 2. Execute a shell command
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. Write a script file
        await sandbox.files.write_files([
            WriteEntry(
                path="/tmp/hello.sh",
                data="echo \"Hello $1\"\necho '2 + 2 =' $((2 + 2))",
                mode=755,
            )
        ])

        # 4. Read the file back
        content = await sandbox.files.read_file("/tmp/hello.sh")
        print(f"Content: {content}")

        # 5. Execute the script
        execution = await sandbox.commands.run("sh /tmp/hello.sh OpenSandbox")
        for log in execution.logs.stdout:
            print(log.text)

    finally:
        # 6. Cleanup the sandbox
        await sandbox.destroy()

if __name__ == "__main__":
    asyncio.run(main())

示例

通过你希望代理执行的操作来探索示例。可运行的源代码位于 examples/ 中。

查看更多编码代理、框架集成、远程开发环境、Kubernetes 部署及存储方案，请参见 完整示例目录。

软件开发工具包

选择你的语言：

pip install opensandbox

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

<dependency>
    <groupId>com.alibaba.opensandbox</groupId>
    < 工件ID > 沙箱 < /工件ID >
    < 版本 > {latest_version} < /版本 >
</dependency>

npm 安装 @alibaba-group/opensandbox

dotnet 添加包 Alibaba.OpenSandbox

去获取 github.com/alibaba/OpenSandbox/sdks/sandbox/go

命令行工具

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 服务器向支持 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。

官方容器镜像

OpenSandbox 发布的镜像在三个官方注册表中使用相同的组件名称发布：

• Docker Hub: docker.io/opensandbox/<component>
• GitHub 容器注册表: ghcr.io/opensandbox-group/opensandbox/<component>
• 阿里云容器注册表: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/<component>

带标签的发布镜像使用 Cosign 无密钥签名，并包含来源证明。在生产中通过摘要固定镜像，并按照 发布验证指南 在部署前验证镜像与 OpenSandbox GitHub Actions 身份的一致性。

文档

• 网站 — 项目主页和文档站点
• 架构 — 系统设计和组件职责
• 部署指南 — Kubernetes 安装和操作
• 服务器配置 — 运行时和服务器设置
• SDK 参考 — 语言指南和功能覆盖
• CLI 指南 — 安装和命令参考
• MCP 集成 — 支持 MCP 的客户端设置
• API 参考 — 沙箱生命周期和执行契约
• 凭证保险库 — 出站凭证注入
• 发布验证 — 镜像签名和工件验证
• 增强提案 — 设计提案和技术方向
• 路线图 — 项目优先级和计划

联系与讨论

• 问题：通过 GitHub Issues 提交漏洞、功能请求或设计讨论
• Discord：加入 OpenSandbox Discord 社区
• 钉钉：加入 OpenSandbox 技术讨论群

关于

OpenSandbox 是 Agentic AI Foundation (AAIF) 的一个项目。

根据 Apache 2.0 许可证 授权。