Sandbox 沙箱使用指南（Beta)

⚠️ Beta 功能: Sandbox 功能目前处于 Beta 阶段，API 和功能可能会有变动。

CodeBuddy 支持在隔离的沙箱环境中运行，提供安全的代码执行和项目开发环境。

🎯 沙箱类型

Container Sandbox （容器沙箱）：基于 Docker/Podman 的本地容器环境
E2B Sandbox （云端沙箱）：基于 E2B 云服务的远程隔离环境
Teleport 模式（远程连接）：连接到已部署的远程沙箱服务

🚀 快速开始

Container Sandbox （容器）

bash

# 基本使用 - 自动挂载当前目录
codebuddy --sandbox "帮我分析这个项目"

# 等价于
codebuddy --sandbox container "帮我分析这个项目"

# 管道模式
echo "运行测试" | codebuddy --sandbox --print

前置要求:

安装 Docker 或 Podman
确保 Docker daemon 运行中

E2B Sandbox （云端）

bash

# 设置 E2B API Key
export E2B_API_KEY=your_api_key

# 基本使用 （需要完整的 API URL)
codebuddy --sandbox https://api.e2b.dev "创建一个 Python web 应用"

# 上传当前工作目录
codebuddy --sandbox https://api.e2b.dev --sandbox-upload-dir "分析这个项目"

Teleport 模式（远程连接）

Teleport 模式用于连接到 BGA (Background Agent) 后台已创建的远程沙箱环境。这是一种特殊的连接模式，主要用于云端调度场景。

bash

# 使用 teleport 值连接到远程沙箱
codebuddy --teleport session_abc123XYZ4567890 "连接到远程沙箱"

# 自定义请求头 （用于认证或路由）
codebuddy --teleport session_abc123XYZ4567890 \
  -H "X-Domain: example.com" \
  -H "X-Enterprise-Id: ent123" \
  "执行任务"

Teleport 值格式:

格式： session_{cliSessionId}
cliSessionId：唯一的会话标识符
示例： session_abc123XYZ4567890

工作原理:

BGA 后台生成唯一的 cliSessionId
BGA 在沙箱中将代码 clone 到 /workspace/{cliSessionId} 目录
BGA 生成 teleport 命令： codebuddy --teleport session_{cliSessionId}
CLI 解析 teleport 值，连接到指定沙箱并切换到正确的工作目录
以 root 用户身份在沙箱中执行命令

前置要求:

有效的 teleport 值（由 BGA 后台生成）
正确的认证凭证（通过 E2B_API_KEY 或 CODEBUDDY_AUTH_TOKEN)
网络连通性到 BGA 后台服务

特点:

代码已由 BGA 后台准备，无需上传
自动使用 root 用户执行命令
工作目录自动设置为 /workspace/{cliSessionId}
支持自定义 HTTP 请求头进行认证和路由

📦 沙箱复用机制

别名系统

为用户/项目分配独立沙箱：

bash

# 使用用户 ID 作为别名
codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "任务"

# 使用项目名作为别名
codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "任务"

别名映射存储在 ~/.codebuddy/sandbox-state.json,支持自动创建和复用。

默认行为

沙箱自动复用，无需手动指定 ID:

bash

# 第一次 - 创建新沙箱
$ codebuddy --sandbox https://api.e2b.dev "Hello"
[Sandbox] Creating new E2B sandbox...
[Sandbox] Created new sandbox: sb_abc123

# 再次启动 - 自动复用
$ codebuddy --sandbox https://api.e2b.dev "继续工作"
[Sandbox] Reusing sandbox: sb_abc123

多项目管理

一个沙箱可托管多个项目，自动隔离在不同目录：

/workspace/
  ├── home-user-projectA/
  ├── home-user-projectB/
  └── var-www-website/

⚙️ 高级参数

沙箱创建和连接

bash

# 强制创建新沙箱 （忽略缓存）
codebuddy --sandbox --sandbox-new "从头开始"

# 连接到指定沙箱 ID （真实 ID)
codebuddy --sandbox --sandbox-id sb_abc123 "继续上次的工作"

# 使用别名 （自定义名称，自动创建和复用）
codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "任务"     # 用户ID
codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "任务"  # 项目名
codebuddy --sandbox https://api.e2b.dev --sandbox-id team-backend -p "任务" # 团队名

# 退出时终止沙箱 （默认保持运行以便复用）
codebuddy --sandbox --sandbox-kill "完成后清理"

环境变量配置

bash

# E2B 配置
export E2B_API_KEY=your_api_key              # 必需
export E2B_TEMPLATE=base                     # 模板名称 (默认: base)
export E2B_TIMEOUT_MS=3600000                # 超时时间 (默认: 1小时)
export E2B_ALLOW_INTERNET_ACCESS=true        # 允许互联网访问 (默认: true)

# Container Sandbox 配置
export CODEBUDDY_SANDBOX_IMAGE=node:20-alpine  # Docker 镜像

📊 沙箱管理

列出沙箱

bash

$ codebuddy sandbox list
E2B Sandboxes:
* sb_abc123 （2 projects, last used 2m ago)
  sb_xyz789 （1 project, last used 2h ago)

查看详情

bash

# 查看当前沙箱
$ codebuddy sandbox info

# 查看指定沙箱
$ codebuddy sandbox info sb_xyz789

终止沙箱

bash

$ codebuddy sandbox kill sb_abc123

清理失效沙箱

bash

$ codebuddy sandbox clean

🔍 工作原理

项目目录映射

bash

本地路径： /Users/yangsubo/projectA
沙箱路径： /workspace/Users-yangsubo-projectA

状态持久化

沙箱状态保存在 ~/.codebuddy/sandbox-state.json

💡 最佳实践

1. 选择合适的沙箱类型

bash

# 需要本地容器隔离
codebuddy --sandbox container "本地开发任务"

# 云端协作或无本地环境
codebuddy --sandbox https://api.e2b.dev "云端开发"

# 连接到远程部署的沙箱服务
codebuddy --teleport session_abc123XYZ4567890 "远程开发"

2. 项目隔离

bash

cd ~/work/projectA
codebuddy --sandbox "开发功能 X"

cd ~/work/projectB
codebuddy --sandbox "修复 bug Y"

3. 长期开发

bash

# 第一天
codebuddy --sandbox "搭建开发环境"

# 第二天 - 秒级启动，环境保留
codebuddy --sandbox "继续开发"

4. 临时任务

使用 --sandbox-kill 自动清理：

bash

codebuddy --sandbox --sandbox-kill "快速测试一个想法"

5. 定期清理

bash

# 查看所有沙箱
codebuddy sandbox list

# 清理失效的
codebuddy sandbox clean

# 手动终止特定沙箱
codebuddy sandbox kill sb_old123

⚠️ 注意事项

Container Sandbox

挂载模式：容器沙箱自动挂载当前目录，文件修改实时同步
网络隔离: Docker 容器与主机网络隔离
资源限制：受 Docker 配置限制

E2B Sandbox

上传延迟：首次上传项目需要时间，文件越多越慢
文件同步：不支持自动同步，需要重新上传或手动同步
费用: E2B 云服务可能产生费用，请查看官方定价
超时：沙箱有最大运行时间限制（默认 1 小时）

交互式命令

E2B 和 Container 都支持交互式 PTY:

bash

codebuddy --sandbox "用 vim 编辑 main.py"
codebuddy --sandbox "运行 htop 查看进程"

🔧 故障排查

Docker 未运行

bash

Error: Neither Docker nor Podman is available

解决：启动 Docker Desktop 或 Podman

E2B API Key 缺失

bash

Error: E2B_API_KEY environment variable is required

解决: export E2B_API_KEY=your_key_here

沙箱连接失败

bash

Failed to connect to sandbox sb_abc123

解决：沙箱可能已过期，使用 --sandbox-new 创建新的

查看调试日志

bash

codebuddy --sandbox --debug "测试命令"

📚 相关文档

CLI 参考 - 完整命令行参数说明
E2B 官方文档 - E2B 云服务文档

Sandbox 沙箱使用指南 （Beta) ​

🎯 沙箱类型 ​

🚀 快速开始 ​

Container Sandbox （容器） ​

E2B Sandbox （云端） ​

Teleport 模式 （远程连接） ​

📦 沙箱复用机制 ​

别名系统 ​

默认行为 ​

多项目管理 ​

⚙️ 高级参数 ​

沙箱创建和连接 ​

环境变量配置 ​

📊 沙箱管理 ​

列出沙箱 ​

查看详情 ​

终止沙箱 ​

清理失效沙箱 ​

🔍 工作原理 ​

项目目录映射 ​

状态持久化 ​

💡 最佳实践 ​

1. 选择合适的沙箱类型 ​

2. 项目隔离 ​

3. 长期开发 ​

4. 临时任务 ​

5. 定期清理 ​

⚠️ 注意事项 ​

Container Sandbox ​

E2B Sandbox ​

交互式命令 ​

🔧 故障排查 ​

Docker 未运行 ​

E2B API Key 缺失 ​

沙箱连接失败 ​

查看调试日志 ​

📚 相关文档 ​

Sandbox 沙箱使用指南（Beta)

🎯 沙箱类型

🚀 快速开始

Container Sandbox （容器）

E2B Sandbox （云端）

Teleport 模式（远程连接）

📦 沙箱复用机制

别名系统

默认行为

多项目管理

⚙️ 高级参数

沙箱创建和连接

环境变量配置

📊 沙箱管理

列出沙箱

查看详情

终止沙箱

清理失效沙箱

🔍 工作原理

项目目录映射

状态持久化

💡 最佳实践

1. 选择合适的沙箱类型

2. 项目隔离

3. 长期开发

4. 临时任务

5. 定期清理

⚠️ 注意事项

Container Sandbox

E2B Sandbox

交互式命令

🔧 故障排查

Docker 未运行

E2B API Key 缺失

沙箱连接失败

查看调试日志

📚 相关文档