容器化

Pi 默认以全部权限运行，但某些情况下，你可能希望对 Pi 可写入的目录以及它拥有的访问权限有更多控制。

有两种通用方案，你可以：

在隔离环境中运行整个 pi 进程，或
在宿主机上运行 pi，把工具（tool）的执行路由到隔离环境中。

选择模式

模式	隔离范围	适用场景	备注
Gondolin extension	内置工具和 `!` 命令	本地微虚拟机隔离，同时将身份验证（authentication）保留在宿主机上	参见 `examples/extensions/gondolin/`。
Plain Docker	本地容器中的整个 `pi` 进程	简单的本地隔离	模型提供方（provider）的 API 密钥会进入容器。
OpenShell	策略控制沙箱（sandbox）中的整个 `pi` 进程	本地或远程托管沙箱	需要一个 OpenShell 网关

扩展（extension）在 pi 进程运行的位置运行。如果你在宿主机上运行 pi 并使用了工具路由扩展，那么其他自定义扩展工具仍会在宿主机上运行，除非它们也将自身的操作委托出去。

Gondolin

Gondolin 是一个本地 Linux 微虚拟机。当你希望 pi 运行在宿主机上、但所有内置工具都路由到虚拟机中时，请使用示例扩展。

设置：

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

该扩展将宿主机当前工作目录挂载到虚拟机中的 /workspace，并覆盖 read、write、edit、bash、grep、find 和 ls。用户的 ! 命令也会被路由到虚拟机中。/workspace 下的文件修改会直接写回宿主机。

要求：@earendil-works/gondolin 需要 Node.js >= 23.6.0，另外还需要 QEMU（需通过你的包管理器安装）。

Plain 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 示例中一样。

如果你想要容器本地的设置（settings）和会话（session），请为 /root/.pi/agent 使用命名卷。挂载宿主机的 ~/.pi/agent 会把宿主机的身份验证和会话文件暴露给容器。

OpenShell

当你需要一个对文件系统、进程、网络、凭据（credential）和推理进行策略控制的沙箱时，请使用 NVIDIA OpenShell。OpenShell 可以通过本地网关（由 Docker、Podman 或虚拟机运行时支持）或远程 Kubernetes 网关运行沙箱。

每个沙箱都需要一个激活的网关。在创建沙箱之前，先注册并选择网关：

openshell gateway add <gateway-url> --name <name>
openshell gateway select <name>

在 OpenShell 沙箱中启动 pi：

openshell sandbox create --name pi-sandbox --from pi -- pi

在这种模式下，整个 pi 进程在沙箱中运行。内置工具、! 命令和扩展工具都在 OpenShell 边界内执行。

如果网关是远程的，项目文件不会从宿主机进行绑定挂载，这意味着沙箱中的写入不会反映到你的机器上。请在沙箱内克隆仓库，或使用 OpenShell 的文件传输命令：

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

OpenShell 模型提供方可以将原始模型 API 密钥保存在沙箱之外。当配置了推理路由时，沙箱内的代码可以调用 https://inference.local，网关会在上游注入所配置的模型提供方凭据。如果你希望模型流量走这条路由，请将 Pi 配置为使用相应的 OpenAI 兼容或 Anthropic 兼容端点。