コンテナ化

Pi はデフォルトですべての権限で実行されますが、Pi が書き込めるディレクトリやアクセス権をより細かく制御したい場合があります。

一般的に 2 つの選択肢があります。

分離環境内で pi プロセス全体を実行する、または
ホストで pi を実行し、ツール実行を分離環境にルーティングする。

パターンの選択

パターン	分離対象	最適な用途	備考
Gondolin 拡張	組み込みツールと `!` コマンド	認証をホストに残しつつローカル micro-VM で分離	`examples/extensions/gondolin/` を参照。
プレーン Docker	ローカルコンテナ内の `pi` プロセス全体	シンプルなローカル分離	Provider API キーがコンテナに入る。
OpenShell	ポリシー制御サンドボックス内の `pi` プロセス全体	ローカルまたはリモート管理サンドボックス	OpenShell ゲートウェイが必要

拡張は pi プロセスが実行される場所で動作します。ツールルーティング拡張でホスト上の pi を実行する場合、他のカスタム拡張ツールも操作を委譲しない限りホスト上で実行されます。

Gondolin

Gondolin はローカル Linux micro-VM です。ホスト上で pi を実行しつつ、すべての組み込みツールを VM にルーティングしたい場合は、サンプル拡張を使用します。

セットアップ：

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 を VM 内の /workspace にマウントし、read、write、edit、bash、grep、find、ls をオーバーライドします。ユーザー ! コマンドも VM にルーティングされます。 /workspace 以下のファイル変更はホストに書き戻されます。

要件：@earendil-works/gondolin 用に Node.js >= 23.6.0、および 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

ファイルシステム、プロセス、ネットワーク、認証情報、推論を制御するポリシーサンドボックスが必要な場合は NVIDIA OpenShell を使用します。 OpenShell は Docker、Podman、または VM ランタイムでバックエンドされるローカルゲートウェイ、またはリモート 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 境界内で実行されます。

ゲートウェイがリモートの場合、プロジェクトファイルはホストから bind-mount されず、サンドボックス内の書き込みはマシンに反映されません。サンドボックス内でリポジトリをクローンするか、OpenShell ファイル転送コマンドを使用してください：

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

OpenShell provider は生のモデル API キーをサンドボックス外に保持できます。推論ルーティングが設定されている場合、サンドボックス内のコードは https://inference.local を呼び出せ、ゲートウェイが上流に設定された provider 認証情報を注入します。モデルトラフィックをこのルートで使用する場合、Pi を対応する OpenAI 互換または Anthropic 互換エンドポイントを使用するよう設定してください。