容器化

默认情况下，Pi以所有权限运行，但在某些情况下，您需要更多地控制Pi可以写入的目录以及它具有哪些访问权限。

有两个一般选项。你可以

在隔离环境中运行整个 pi 进程，或者
在主机上运行 pi 并将工具执行路由到隔离环境中。

选择图案

图案	什么是孤立的	最适合	笔记
Gondolin 扩展	内置工具和`!`命令	本地微虚拟机隔离，同时在主机上保持身份验证	参见`examples/extensions/gondolin/`。
普通Docker	本地容器中的整个`pi`过程	简单的本地隔离	提供者API key进入容器。
OpenShell	整个`pi`过程在政策控制sandbox中	本地或远程管理 sandbox	需要OpenShell网关

Extensions 在 pi 进程运行的地方运行。如果您使用工具路由扩展运行主机 pi，其他自定义扩展工具仍会在主机上运行，除非它们也委托其操作。

Gondolin

Gondolin 是本地 Linux 微型虚拟机。当您希望在主机上使用 pi 但将所有内置工具路由到 VM 中时，请使用 example extension。

设置：

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 安装在虚拟机中的 /workspace 处，并覆盖 read、write、edit、bash、grep、find 和 ls。用户 ! 命令也被路由到虚拟机中。 /workspace下的文件更改写入主机。

要求：Node.js >= 23.6.0（对于 @earendil-works/gondolin），加上 QEMU（需要通过包管理器安装）。

普通Docker

当您想要最简单的本地容器边界时，请在Docker中运行整个pi流程。

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 的命名卷。挂载主机 ~/.pi/agent 会将主机身份验证和会话文件公开给容器。

OpenShell

当您需要具有文件系统、进程、网络、凭据和推理控制的策略控制 sandbox 时，请使用NVIDIA OpenShell。 OpenShell 可以通过Docker、Podman 或 VM 运行时支持的本地网关，或通过远程 Kubernetes 网关运行 sandboxes。

每个sandbox都需要一个活动网关。在创建 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 边界内执行。

如果网关是远程的，则项目文件不会从主机绑定安装，这意味着 sandbox 中的写入不会反映在您的计算机上。在sandbox内克隆存储库或使用OpenShell文件传输命令：

openshell sandbox upload pi-sandbox ./repo /workspace
openshell sandbox download pi-sandbox /workspace/repo ./repo-out

OpenShell 提供商可以将原始模型 API key 保留在 sandbox 之外。配置推理路由后，sandbox内的代码可以调用https://inference.local，并且网关将配置的提供者凭据注入上游。如果您希望模型流量使用此路由，请配置 Pi 使用相应的 OpenAI 兼容或 Anthropic 兼容端点。