Agent Sandbox 实战：用 Docker 隔离你的 AI 编码 Agent，安全运行不被“越狱”
AI 编码 Agent（Claude Code、Codex、Cursor、OpenCode）在帮你写代码时，本质上是把你的文件系统、Git 凭据、环境变量、网络访问权限全部交给了一个外部 LLM 控制。正常情况下它帮你改代码，但如果它被 prompt injection 攻击、或者 Agent 框架本身有 bug，一个 rm -rf / 或恶意脚本就足以造成严重破坏。
Agent Sandbox 是一个轻量级的 Docker 沙箱方案——把 AI 编码 Agent 跑在隔离的 Docker 容器里，Agent 拿不到宿主机 root 权限、碰不到 Docker socket、也无法随意访问网络。本文带你从头部署和配置它。
为什么需要沙箱？
现代 AI 编码 Agent 的权限模型是”全有或全无”：
- 文件系统：Agent 可以读写你当前目录及子目录中的所有文件
- 网络：Agent 可以自由访问互联网——安装 npm 包、调用 API、甚至向外部发送你的代码
- 凭据：Agent 可以访问你的环境变量、.env 文件、SSH 密钥、AWS 凭证
- Docker socket：许多 Agent 框架在宿主机上运行，如果有漏洞，Agent 可能接管 Docker 守护进程
rm -rf / 是夸张，但更现实的场景是：Agent 被 prompt injection 诱导将 .env 文件内容发送到外部服务器。一个隔离的 Docker 容器能有效防止这类问题。
Agent Sandbox 是什么
Agent Sandbox（GitHub: marvincaspar/agent-sanbox）是一个轻量级的 bash + Docker 包装器，目前支持 pi 和 opencode 两个 AI 编码 Agent。它通过多层安全策略实现隔离：
- 无 root 权限：容器以宿主机 UID 运行，
--cap-drop=ALL - 无特权升级：
--no-new-privileges禁止容器内提权 - 无 Docker socket：Agent 看不到宿主机上的 Docker 守护进程
- 无系统包管理：容器内没有 root，无法安装系统级软件
- 可选网络隔离：通过代理 sidecar 做网络白名单
安装 Agent Sandbox
git clone https://github.com/marvincaspar/agent-sanbox.git cd agent-sanbox
项目结构很直接——每个 Agent 有自己的子目录和 Dockerfile：
agent-sanbox/ ├── pi/ │ ├── Dockerfile │ ├── pi # bash 包装脚本 │ └── entrypoint.sh ├── opencode/ │ ├── Dockerfile │ ├── opencode # bash 包装脚本 │ └── entrypoint.sh └── README.md
安装包装脚本到系统路径：
ln -sf "$(pwd)/pi/pi" /usr/local/bin/pi ln -sf "$(pwd)/opencode/opencode" /usr/local/bin/opencode
首次运行时构建 Docker 镜像：
pi --build
--build 会构建所有语言变体镜像（base、go、php8.4、php8.5），基于 Chainguard 的安全基础镜像。
基础使用
在当前目录启动 pi Agent（无网络限制）：
cd /path/to/your/project pi
容器自动构建，挂载当前工作目录，Agent 可以读写项目文件但不能逃逸到其他目录。
指定语言运行时：
pi --lang go # 带 Go 1.26 的镜像 pi --lang php8.5 # 带 PHP 8.5 的镜像
这会在基础镜像上叠加对应语言的 SDK——适合 Agent 需要编译或运行特定语言代码的场景。
对于 opencode，用法完全对称：
opencode opencode --lang go opencode --build
代理 sidecar：网络白名单控制
Agent Sandbox 的亮点是 网络隔离模式。当不加 --proxy 参数时，Agent 容器拥有完全的互联网访问——这适合大多数日常开发场景。但如果你正在处理敏感代码，或者只是想严格限制 Agent 的行为：
pi --proxy
--proxy 标志启动一个 tinyproxy sidecar 容器：
- Agent 容器被放入一个隔离的内部 Docker 网络，没有任何出站网络（没有互联网访问）
- 所有出站流量被强制通过 tinyproxy 代理容器
- 代理容器根据白名单文件
~/.agents/proxy_allowed_domains.txt过滤目标地址 - 默认拒绝所有未在白名单中的域名
配置你的白名单：
mkdir -p ~/.agents cat > ~/.agents/proxy_allowed_domains.txt << 'EOF' github.com api.github.com raw.githubusercontent.com *.githubusercontent.com registry.npmjs.org registry.yarnpkg.com *.your-company.com host.docker.internal EOF
白名单支持通配符：*.example.com 匹配 api.example.com、auth.example.com 等所有子域名。
安全模型详解
Agent Sandbox 的容器安全配置在 Docker 层面做了四层防御：
容器启动参数： --cap-drop=ALL ← 丢弃所有 Linux 内核能力 --security-opt=no-new-privileges:true ← 禁止提权 --user $HOST_UID ← 以宿主机 UID 运行（非 root） --network (隔离网络) ← 受控网络（proxy 模式）
与在宿主机上直接运行 Agent 相比：
| 维度 | 宿主机运行 | Agent Sandbox |
|---|---|---|
| 文件系统 | 可读写整个项目目录及子目录 | 仅容器挂载的当前目录 |
| 系统文件 | 可读写 ~/.ssh、~/.aws、/etc 等 | 容器内有独立文件系统，看不到宿主 |
| Docker socket | 如有漏洞可接管 Docker | 容器内无 Docker |
| 网络 | 完全互联网访问 | 可选白名单限制 |
| 提权 | 依赖 Agent 自身安全 | --no-new-privileges 强制禁止 |
| 持久化 | Agent 可修改宿主机持久化配置 | 无持久化逃逸能力 |
工作原理
每次运行 pi 或 opencode 时，包装脚本执行以下流程：
- 构建镜像：首次运行时构建所有语言变体，或
--build强制重新构建 - 创建网络：如果启用了
--proxy，创建隔离的内部 Docker 网络 - 启动 sidecar：如果是 proxy 模式，启动 tinyproxy 容器并读取白名单
- 运行 Agent：启动 Agent 容器，挂载当前工作目录，设置安全参数
- 清理：Agent 退出后，自动停止 proxy 容器并移除网络
基础镜像基于 Chainguard 的 node:latest-dev，包含 Node.js + npm、Git、curl 和 CA 证书，足够 Agent 正常执行代码和安装依赖。
实战：在沙箱中运行 Agent 处理敏感项目
假设你要用 AI Agent 处理一个包含客户数据的项目：
cd /home/me/customer-portal/ cat > ~/.agents/proxy_allowed_domains.txt << 'EOF' github.com api.github.com npmjs.org registry.npmjs.org EOF pi --proxy
代理模式的可选允许列表文件：
pi --proxy --allowed-domains /path/to/custom_allowlist.txt
总结
Agent Sandbox 解决了 AI 编码 Agent 安全运行中的一个基础问题：权限最小化。它不依赖 Agent 自身的安全设计，而是在基础设施层做隔离。虽然目前只支持 pi 和 opencode 两个 Agent，但项目架构（Dockerfile + bash wrapper）可以很容易地扩展到其他 Agent。
对于处理敏感代码、合规要求严格的团队，或者在不受信任的 CI 环境中运行 AI Agent，这种容器级沙箱是必要的安全措施。它不能替代 prompt 安全训练、敏感数据脱敏等工作，但作为第一道防线，Docker 隔离是最低成本、最高回报的安全手段。
相关链接