compose-anything/apps/opensandbox/README.zh.md

OpenSandbox

English | 中文

一个通用的 AI 应用沙箱平台，提供多语言 SDK、统一的沙箱 API 以及 Docker/Kubernetes 运行时。适用于代码智能体、GUI 智能体、智能体评估、AI 代码执行和强化学习训练等场景。

功能特性

• 多语言 SDK 支持：提供 Python、JavaScript/TypeScript、Java/Kotlin 和 Go 客户端 SDK
• 统一的沙箱 API：为沙箱生命周期、命令执行和文件操作提供一致的接口
• 多种运行时选项：支持 Docker 和 Kubernetes 运行时
• 安全加固：内置安全特性，包括能力限制、特权提升防护和资源限制
• 灵活的配置：支持各种网络模式、资源约束和安全配置
• 代码解释器：预构建的镜像，支持 Python、Node.js、Java 和 Go 内核

快速开始

前置要求

• Docker Engine（Docker 运行时必需）
• Docker Compose
• 足够的权限访问 Docker socket

使用 Colima 的 macOS 用户注意：您需要在启动 OpenSandbox 之前设置 DOCKER_HOST 环境变量：

export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

部署

1. 复制环境文件并根据需要配置：

   cp .env.example .env
   

2. 编辑 config.toml 设置您的 API 密钥：

   [server]
   api_key = "your-secret-api-key-change-this"
   

   重要：在生产环境中必须更改默认的 API 密钥！

3. 启动服务：

   docker compose up -d
   

4. 验证服务是否运行：

   curl http://localhost:8080/health
   

   您应该收到成功的健康检查响应。

配置

环境变量

主要环境变量（完整列表见 .env.example）：

变量	描述	默认值
OPENSANDBOX_SERVER_VERSION	OpenSandbox 服务器镜像版本	v1.0.5
OPENSANDBOX_SERVER_PORT_OVERRIDE	主机端口映射	8080
DOCKER_HOST	Docker socket 路径	unix:///var/run/docker.sock
OPENSANDBOX_SERVER_CPU_LIMIT	CPU 核心限制	2.0
OPENSANDBOX_SERVER_MEMORY_LIMIT	内存限制	2G

服务器配置

主配置文件为 config.toml。主要配置部分：

• [server]：HTTP 服务器设置（主机、端口、日志级别、API 密钥）
• [runtime]：运行时类型和 execd 镜像配置
• [docker]：Docker 特定设置，包括网络模式和安全选项

网络模式

• bridge（推荐）：容器拥有隔离的网络，支持多个沙箱
• host：容器共享主机网络，一次只能运行一个沙箱实例

安全特性

• 能力限制：从容器中移除危险的 Linux 能力
• 特权提升防护：阻止容器内的特权提升
• 进程限制：控制每个沙箱的最大进程数
• AppArmor/Seccomp 配置文件：可选的安全配置文件（留空使用 Docker 默认值）

使用方法

基本沙箱创建（Python SDK）

from opensandbox import Sandbox
from datetime import timedelta

# 创建一个代码解释器沙箱
sandbox = await Sandbox.create(
    "opensandbox/code-interpreter:v1.0.1",
    entrypoint="/opt/opensandbox/code-interpreter.sh",
    env={"PYTHON_VERSION": "3.11"},
    timeout=timedelta(minutes=10)
)

async with sandbox:
    # 执行 Python 代码
    result = await sandbox.execute(
        "python",
        "-c",
        "print('Hello from OpenSandbox!')"
    )
    print(result.stdout)

API 认证

所有 API 请求都需要在 X-API-Key 头中包含 config.toml 中配置的密钥：

curl -H "X-API-Key: your-secret-api-key-change-this" \
     http://localhost:8080/sandboxes

预构建镜像

OpenSandbox 提供了几个预构建的沙箱镜像：

• opensandbox/code-interpreter：多语言代码解释器（Python、Node.js、Java、Go）
• opensandbox/vscode：VS Code Server 环境
• opensandbox/desktop：支持 VNC 的完整桌面环境
• opensandbox/playwright：使用 Playwright 进行浏览器自动化
• opensandbox/chrome：Chromium 浏览器环境

端口

端口	服务	描述
8080	OpenSandbox Server	HTTP API 服务器

数据持久化

• opensandbox_data：服务器数据和状态

健康检查

该服务在 /health 端点提供内置的健康检查：

curl http://localhost:8080/health

安全注意事项

Docker Socket 访问

此服务需要访问 Docker socket（/var/run/docker.sock）以创建和管理沙箱容器。这是一个高权限操作。

安全影响：

• 具有 Docker socket 访问权限的容器可能会控制主机系统
• 仅在受信任的环境中部署
• 在生产环境中考虑使用 Docker-in-Docker 或 rootless Docker 以获得额外的隔离

替代方案：

• 使用 Kubernetes 运行时而不是 Docker 运行时（需要 Kubernetes 集群）
• 使用受限用户权限和资源配额进行部署

API 密钥安全

• 切勿在生产环境中使用默认 API 密钥
• 安全存储 API 密钥（例如，使用 Docker secrets、密钥管理器的环境变量）
• 定期轮换 API 密钥
• 限制网络暴露（使用防火墙规则、反向代理）

资源限制

始终配置适当的 CPU 和内存限制以防止资源耗尽：

deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G

故障排除

Docker Socket 连接问题

错误：Failed to initialize Docker service

解决方案：

• 确保 Docker Desktop/Engine 正在运行
• 在使用 Colima 的 macOS 上：设置 DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock
• 检查 Docker socket 权限：ls -l /var/run/docker.sock

健康检查失败

错误：Health check timeout

解决方案：

• 检查容器日志：docker compose logs opensandbox-server
• 验证服务是否成功启动：docker compose ps
• 如果服务需要更多时间初始化，增加 docker-compose.yaml 中的 start_period

沙箱创建失败

错误：Failed to create sandbox

解决方案：

• 确保 execd 镜像可访问：docker pull opensandbox/execd:v1.0.5
• 检查可用的系统资源（CPU、内存、磁盘空间）
• 查看服务器日志以获取详细的错误消息

许可证

此项目是 OpenSandbox 套件的一部分。详情请参阅主 LICENSE 文件。

参考资料

• OpenSandbox GitHub 仓库
• OpenSandbox 文档
• Docker 安全

支持

如有问题和疑问：

• GitHub Issues
• 官方文档