貨櫃化

預設情況下，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 相容端點。