容器化

Pi 默认拥有所有权限，但在某些情况下，你可能希望对 Pi 可以写入的目录范围以及它拥有的访问权限进行更精细的控制。

有两种基本方法：

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

选择一种模式

模式	隔离对象	适用场景	备注
Gondolin 扩展	内置工具和 ! 命令	保留宿主机认证的同时实现本地微 VM 隔离	参见 examples/extensions/gondolin/。
纯 Docker	整个 pi 进程在本地容器中	简单的本地隔离	提供者 API 密钥会进入容器。
OpenShell	整个 pi 进程在策略控制的沙盒中	本地或远程托管沙盒	需要 OpenShell 网关。

扩展在 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 下的文件更改会写回宿主机。

要求：Node.js >= 23.6.0（用于 @earendil-works/gondolin），以及通过包管理器安装的 QEMU。

纯 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。挂载宿主机的 ~/.pi/agent 会将认证文件和会话文件暴露给容器。

OpenShell

当你需要策略控制的沙盒（具有文件系统、进程、网络、凭证和推理控制）时，请使用 NVIDIA OpenShell。OpenShell 可以通过本地网关（后端为 Docker、Podman 或虚拟机运行时）或远程 Kubernetes 网关运行沙盒。

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

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

在 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 兼容端点。