Agentbox - 编码智能体沙盒

目前还没有完美的智能体沙盒方案，但容器是一个实用的起点。

Agentbox 是一个基于 Docker 的编码智能体沙盒，最初受 Batrachian Toad 启发，现已泛化以支持更多工具。它提供了一个隔离环境，可与 webterm 配合良好，用于运行多个智能体会话。

功能特性

默认容器提供：

• 开发环境：Debian Trixie，附带常用开发工具
• 预装编码智能体：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：当容器以特权模式运行时可用
• 远程访问：SSH（ENABLE_SSH=true）和 mosh 支持
• 工作区引导：内置工作区骨架和智能体技能，位于 /home/agent/workspace-skel

路线图

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

服务配置

Agentbox 通过环境变量控制容器启动时开启的服务：

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

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

示例：

# 默认 - 所有服务禁用
docker run -d agentbox

# 仅启用 Docker 守护进程
docker run -d -e ENABLE_DOCKER=true agentbox

# 为开发启用 Docker 和 SSH
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -p 22:22 agentbox

# 完整的桌面体验，启用所有服务（GUI 镜像）
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   # 或：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

# 构建无头镜像
docker build -t agentbox .

# 构建 GUI 镜像
docker build -t agentbox:gui --target gui .

# 运行容器并选择服务（GUI 镜像）
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（聊胜于无）。
• 建议使用 SSH 密钥而非密码认证。
• 生产环境中，建议禁用不必要的服务并更改默认凭据。

致谢

本项目松散地基于我古老的 rcarmo/docker-templates/desktop-chrome，并更新了用户空间。

许可证

MIT