容器化

Pi 默认以完全权限运行，但在某些情况下，您可能希望对 Pi 可写入的目录及其拥有的访问权限进行更精细的控制。

有两种通用方案可供选择。您可以：

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

选择方案 Choose a pattern

扩展程序运行在 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（需通过包管理器安装）。

纯 Docker 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 示例类似。

如果您需要容器本地的设置和会话，请为 /root/.pi/agent 使用命名卷。将宿主机 ~/.pi/agent 挂载到容器中会暴露宿主机的认证和会话文件。

OpenShell

当您需要具有文件系统、进程、网络、凭据和推理策略控制的沙箱时，请使用 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 兼容端点。