Agentbox - 编码代理沙箱

目前还没有完美的方法来沙箱化代理，但容器是一个实用的起点。

Agentbox 是一个基于 Docker 的编码代理沙箱，最初受 Batrachian Toad 启发，现已推广到更多工具。 它提供了一个隔离环境，与 webterm 配合良好，可用于运行多个代理会话。

功能特性

默认容器提供：

• 开发环境：Debian Stable，包含常用开发工具
• 预装编码代理：Copilot CLI、Codex、Pi
• 预装 CLI 工具：gh、Nushell、lazygit、killall
• 包管理器：Homebrew 和 APT，以及 uv 和 Bun；容器构建会安装最新可用包，不固定精确版本
• 可选代理工具：通过 make -C ~ ... 安装 toad、opencode、gemini 和 vibe
• 服务控制：通过 ENABLE_DOCKER、ENABLE_SSH 和 ENABLE_RDP 切换 Docker/SSH/RDP
• Docker-in-Docker：当容器以特权模式运行时可用
• 远程访问：SSH（ENABLE_SSH=true）和 mosh 支持
• 工作区引导：内置工作区骨架和代理技能，位于 /home/agent/workspace-skel

路线图

• CPU 和内存限制（基础 Docker 资源约束）
• 网络隔离选项
• 其他沙箱技术（gVisor、Kata Containers 等）

服务配置

Agentbox 使用环境变量来控制容器启动时启动哪些服务：

• ENABLE_DOCKER=true - 启动 Docker 守护进程（用于 Docker-in-Docker 支持）
• ENABLE_SSH=true - 启动 SSH 服务器（端口 22）
• ENABLE_RDP=true - 启动 RDP 服务器（端口 3389）
• AGENTBOX_ENVIRONMENT=cli|gui - 镜像提供的环境标记（cli 用于无头/CLI，gui 用于桌面镜像）

默认行为： 除非显式启用，否则所有服务均被禁用。

示例：

# Default - all services disabled
docker run -d agentbox

# Enable only Docker daemon
docker run -d -e ENABLE_DOCKER=true agentbox

# Enable Docker and SSH for development
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -p 22:22 agentbox

# Full desktop experience with all services (GUI image)
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -e ENABLE_RDP=true -p 22:22 -p 3389:3389 agentbox:gui

快速开始

可选工具安装

在容器内，agent 用户自带一个 ~/Makefile，可用于安装额外工具。

可通过 make -C ~ … 安装的编码代理/CLI：

• toad — 安装 Batrachian Toad（通过 uv tool）
• opencode — 安装 OpenCode（通过 Bun）
• gemini — 安装 Gemini CLI（通过 Homebrew）
• vibe — 安装 mistral-vibe（通过 uv tool）

便捷目标：

• tools — 安装 node、go、gemini、vibe
• node、go — 安装语言工具链（某些代理的前置依赖）

工作区骨架

Agentbox 自带一个内置项目骨架，位于 /home/agent/workspace-skel。

要将其复制到当前的 /workspace，且不覆盖现有文件：

make init-workspace

详情请参阅 docs/workspace-skeleton.md。

GUI 镜像

GUI 构建以 :gui 标签发布（也有 <release>-gui），包含 XFCE、XRDP 和 VS Code。

Docker Compose

推荐工作流程：

make up
make enter-toad   # or: make enter-copilot
make down

如果需要服务覆盖，请创建 docker-compose.override.yml：

services:
  toad:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"
  copilot:
    environment:
      ENABLE_DOCKER: "true"
      ENABLE_SSH: "true"

然后运行：

docker compose up -d

直接使用 Docker

# Build the headless image
docker build -t agentbox .

# Build the GUI image
docker build -t agentbox:gui --target gui .

# Run the container with selected services (GUI image)
docker run -d \
  --name agentbox \
  --privileged \
  -e ENABLE_DOCKER=true \
  -e ENABLE_SSH=true \
  -e ENABLE_RDP=true \
  -p 22:22 \
  -p 3389:3389 \
  -v $(pwd):/workspace \
  agentbox:gui

使用 Batrachian Toad

连接到容器后：

1. 安装 Toad（如需要）：

make -C ~ toad

2. 启动 Toad：

toad

3. 或使用特定项目目录启动：

toad /workspace

4. 或直接使用代理启动：

toad -a open-hands

安全注意事项

• 服务控制： 默认情况下，所有服务（Docker、SSH、RDP）均被禁用。请使用环境变量仅显式启用所需服务。
• 默认密码较弱 - 生产环境中请更改
• 容器需要以特权模式运行，以便代理可以使用 Docker-in-Docker（有总比没有好）
• 考虑使用 SSH 密钥代替密码认证
• 生产环境中，请考虑禁用不必要的服务并更改默认凭据

致谢

本项目大致基于我早年的 rcarmo/docker-templates/desktop-chrome，并更新了用户空间。

许可证

MIT