# 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`

**工作原理**:
1. BGA 后台生成唯一的 `cliSessionId`
2. BGA 在沙箱中将代码 clone 到 `/workspace/{cliSessionId}` 目录
3. BGA 生成 teleport 命令： `codebuddy --teleport session_{cliSessionId}`
4. CLI 解析 teleport 值，连接到指定沙箱并切换到正确的工作目录
5. 以 `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 参考](./cli-reference.md) - 完整命令行参数说明
- [E2B 官方文档](https://e2b.dev/docs) - E2B 云服务文档
