Pi 官方文档
容器化
容器化
Pi 默认会以全部权限运行。但在某些场景下，你会希望更细地控制 Pi 可以写入哪些目录，以及它拥有哪些访问权限。
通常有两种方案。你可以：
- 把整个
pi进程运行在隔离环境里，或者 - 让
pi运行在宿主机上，再把 tool execution 路由到隔离环境中。
选择一种模式
| 模式 | 隔离的内容 | 适用场景 | 说明 |
|---|---|---|---|
| Gondolin extension | 内置工具和 ! 命令 | 在宿主机保留认证，同时使用本地 micro-VM 隔离 | 见 examples/extensions/gondolin/。 |
| Plain Docker | 整个 pi 进程运行在本地容器中 | 简单的本地隔离 | Provider API keys 会进入容器。 |
| OpenShell | 整个 pi 进程运行在受策略控制的 sandbox 中 | 本地或远程托管的 sandbox | 需要 OpenShell gateway |
扩展会运行在 pi 进程运行的地方。如果你在宿主机上运行 pi，并使用一个负责路由 tool execution 的扩展，那么其他自定义扩展工具仍然会在宿主机上运行，除非它们也把自己的操作委托出去。
Gondolin
Gondolin 是一个本地 Linux micro-VM。
当你希望 pi 运行在宿主机上，但把所有内置工具都路由到 VM 中时，请使用这个 示例扩展。
设置：
cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
cd ~/.pi/agent/extensions/gondolin
npm install --ignore-scripts
从你想要挂载的项目目录运行：
cd /path/to/project
pi -e ~/.pi/agent/extensions/gondolin
这个扩展会把宿主机的 cwd 挂载到 VM 里的 /workspace，并覆盖 read、write、edit、bash、grep、find 和 ls。
用户的 ! 命令也会被路由到 VM 中。
/workspace 下的文件变更会直接写回宿主机。
要求：@earendil-works/gondolin 需要 Node.js >= 23.6.0，另外还需要 QEMU（需通过你的 package manager 安装）。
Plain Docker
当你想要最简单的本地容器边界时，把整个 pi 进程运行在 Docker 里。
Dockerfile.pi：
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"]
构建并运行：
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-sandbox
-v "$PWD:/workspace" 会把你当前目录挂载到容器内的 /workspace，这样 Docker 里对 /workspace 的读写会直接影响你的宿主机文件，和 Gondolin 示例一样。
如果你希望设置和会话都只保留在容器内，请为 /root/.pi/agent 使用命名 volume。挂载宿主机的 ~/.pi/agent 会把宿主机的认证和会话文件暴露给容器。
OpenShell
当你需要一个带有文件系统、进程、网络、凭据和推理控制的策略管理 sandbox 时，请使用 NVIDIA OpenShell。 OpenShell 可以通过由 Docker、Podman 或 VM runtime 支持的本地 gateway 运行 sandbox，也可以通过远程 Kubernetes gateway 运行。
每个 sandbox 都需要一个已启用的 gateway。 在创建 sandbox 之前，先注册并选择一个：
openshell gateway add <gateway-url> --name <name>
openshell gateway select <name>
在 OpenShell sandbox 中启动 pi：
openshell sandbox create --name pi-sandbox --from pi -- pi
在这种模式下，整个 pi 进程都会运行在 sandbox 内。
内置工具、! 命令和扩展工具都会在 OpenShell 边界内执行。
如果 gateway 是远程的，项目文件不会从宿主机 bind mount 进来，这意味着你在 sandbox 里的写入不会反映到本机。 请在 sandbox 内 clone 仓库，或者使用 OpenShell 文件传输命令：
openshell sandbox upload pi-sandbox ./repo /workspace
openshell sandbox download pi-sandbox /workspace/repo ./repo-out
OpenShell Provider 可以把原始模型 API keys 保留在 sandbox 外部。
当配置了 inference routing 时，sandbox 内的代码可以调用 https://inference.local，gateway 会把已配置的 Provider 凭据带入上游。
如果你希望模型流量走这条路径，请把 Pi 配置为使用对应的 OpenAI-compatible 或 Anthropic-compatible endpoint。