8 容器化
8.1 概述
Pi 默认以全部权限运行，但在某些场景下，你可能需要更多控制——比如限制 Pi 可以写入的目录、隔离网络访问或控制 API Key 的暴露。
Pi 的容器化有两种通用方案：
- 将整个 Pi 进程放入隔离环境中运行
- 在宿主机上运行 Pi，将工具执行路由到隔离环境中
8.2 方案选择
| 方案 | 隔离内容 | 最适合 | 备注 |
|---|---|---|---|
| Gondolin 扩展 | 内置工具和 ! 命令 |
本地微VM 隔离，认证保留在宿主机 | 扩展运行在宿主机上 |
| Plain Docker | 整个 Pi 进程 | 简单的本地隔离 | Provider API Key 进入容器 |
| OpenShell | 整个 Pi 进程 | 本地或远程托管沙箱 | 需要 OpenShell 网关 |
扩展运行在 Pi 进程所在的位置。如果你在宿主机上运行 Pi 并使用工具路由扩展，其他自定义扩展工具仍在宿主机上运行，除非它们也委托了操作。
8.3 Gondolin 微VM 扩展
Gondolin 是一个本地 Linux 微VM。当你想在宿主机上运行 Pi，但将所有内置工具路由到 VM 中执行时，使用此方案。
8.3.1 安装与配置
# 复制示例扩展到 Pi 的扩展目录
cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
cd ~/.pi/agent/extensions/gondolin
npm install --ignore-scripts8.3.2 运行
从你要挂载的项目目录启动：
cd /path/to/project
pi -e ~/.pi/agent/extensions/gondolin8.3.3 工作原理
该扩展将宿主机当前工作目录挂载到 VM 中的 /workspace，并覆盖以下工具：
| 被覆盖的工具 | 说明 |
|---|---|
read |
在 VM 中读取文件 |
write |
在 VM 中写入文件 |
edit |
在 VM 中修补文件 |
bash |
在 VM 中执行命令 |
grep |
在 VM 中搜索 |
find |
在 VM 中查找 |
ls |
在 VM 中列目录 |
用户的 ! 命令也会路由到 VM 中。/workspace 下的文件变更会直接写回宿主机。
8.3.4 系统要求
- Node.js >= 23.6.0（用于
@earendil-works/gondolin） - QEMU（通过包管理器安装）
Gondolin 方案的核心优势是：认证信息（API Key、OAuth 令牌）保留在宿主机上，不会暴露给 VM。只有工作空间文件是共享的。
8.4 Plain Docker
当你需要最简单的本地容器边界时，将整个 Pi 进程放入 Docker 中运行。
8.4.1 Dockerfile
FROM node:24-bookworm-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
&& rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
WORKDIR /workspace
ENTRYPOINT ["pi"]8.4.2 构建与运行
# 构建 Docker 镜像
docker build -t pi-sandbox -f Dockerfile.pi .
# 运行容器
docker run --rm -it \
-e ANTHROPIC_API_KEY \
-v "$PWD:/workspace" \
-v pi-agent-home:/root/.pi/agent \
pi-sandbox8.4.3 挂载说明
| 挂载 | 说明 |
|---|---|
-v "$PWD:/workspace" |
将当前目录挂载到容器中，/workspace 中的读写直接影响宿主文件 |
-v pi-agent-home:/root/.pi/agent |
使用命名卷存储容器内的设置和会话 |
如果你挂载宿主机的 ~/.pi/agent 到容器中，宿主机的认证和会话文件将暴露给容器。仅在确实需要时这样做。
8.4.4 自定义示例
# 使用不同模型运行
docker run --rm -it \
-e OPENAI_API_KEY \
-v "$PWD:/workspace" \
-v pi-agent-home:/root/.pi/agent \
pi-sandbox --provider openai --model gpt-4o
# 只读模式审查代码
docker run --rm -it \
-e ANTHROPIC_API_KEY \
-v "$PWD:/workspace:ro" \
pi-sandbox --tools read,grep,find,ls -p "Review the code"使用 :ro 标志将工作空间以只读方式挂载，为代码审查提供了额外的安全层。
8.5 OpenShell 策略控制沙箱
使用 NVIDIA OpenShell 当你需要一个策略控制沙箱，具有文件系统、进程、网络、凭证和推理控制能力时。
OpenShell 可以通过以下方式运行沙箱：
- 本地网关（由 Docker、Podman 或 VM 运行时支持）
- 远程 Kubernetes 网关
8.5.1 设置网关
每个沙箱需要一个活跃的网关。在创建沙箱前注册并选择一个：
openshell gateway add <gateway-url> --name <name>
openshell gateway select <name>8.5.2 在沙箱中启动 Pi
openshell sandbox create --name pi-sandbox --from pi -- pi在这种方案中，整个 Pi 进程在沙箱内运行。内置工具、! 命令和扩展工具都在 OpenShell 边界内执行。
8.5.3 文件传输
如果网关是远程的，项目文件不会从宿主机绑定挂载。在沙箱内克隆仓库或使用 OpenShell 文件传输命令：
# 上传文件到沙箱
openshell sandbox upload pi-sandbox ./repo /workspace
# 从沙箱下载文件
openshell sandbox download pi-sandbox /workspace/repo ./repo-out8.5.4 推理路由
OpenShell 提供商可以将原始模型 API Key 保留在沙箱之外。当配置了推理路由时，沙箱内的代码可以调用 https://inference.local，网关在上游注入配置的提供商凭证。
配置 Pi 使用相应的 OpenAI 兼容或 Anthropic 兼容端点，如果你希望模型流量走这条路由。
8.6 三种方案对比
| 维度 | Gondolin | Plain Docker | OpenShell |
|---|---|---|---|
| 隔离程度 | 工具级 | 进程级 | 策略级 |
| 认证安全 | ✅ Key 在宿主机 | ⚠️ Key 进入容器 | ✅ Key 在网关 |
| 文件访问 | 仅工作空间 | 整个挂载点 | 可策略控制 |
| 网络控制 | 无 | 需额外配置 | ✅ 内置 |
| 进程控制 | 无 | 需额外配置 | ✅ 内置 |
| 部署复杂度 | 中等 | 低 | 高 |
| 适用场景 | 本地开发 | 简单隔离 | 企业级安全 |
对于大多数个人开发者，Plain Docker 方案足够简单且有效。如果你需要保留认证在宿主机上，选择 Gondolin。如果你需要企业级策略控制，选择 OpenShell。