容器化

預設情況下，Pi 以所有權限執行，但在某些情況下，你需要更多地控制 Pi 可以寫入的目錄以及它具有哪些存取權限。

有兩個一般選項。你可以

在隔離環境中執行整個 pi 程序，或者
在主機上執行 pi 並將工具執行路由至隔離環境中。

選擇模式

圖案	什麼是孤立的	最適合	筆記
Gondolin 擴充	內建工具和 `!` 指令	本機微虛擬機隔離，同時在主機上保持身分驗證	參見`examples/extensions/gondolin/`。
普通 Docker	本機容器中的整個 `pi` 過程	簡單的本機隔離	Provider 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 Provider 可以將原始模型 API Key 保留在 sandbox 之外。設定推理路由後，sandbox 內的程式碼可以呼叫 https://inference.local，並且閘道將設定的 Provider 憑證注入上游。如果你希望模型流量使用此路由，請設定 Pi 使用相應的 OpenAI 相容或 Anthropic 相容端點。