コンテナ化

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

一般的なオプションは 2 つあります。どちらでもできます

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

パターンを選択してください

パターン	何が孤立しているのか	こんな方に最適	注意事項
Gondolin拡張子	組み込みツールと`!` コマンド	ホスト上で認証を維持しながらローカルのマイクロ VM を分離	`examples/extensions/gondolin/`を参照してください。
プレーン Docker	ローカルコンテナ内の`pi`プロセス全体	シンプルなローカル分離	プロバイダー API key がコンテナに入ります。
OpenShell	ポリシー制御された sandbox 内の `pi` プロセス全体	ローカルまたはリモート管理 sandbox	OpenShell ゲートウェイが必要です

Extensions は、pi プロセスが実行される場所であればどこでも実行されます。ツールルーティング拡張機能を使用してホスト pi を実行する場合、他のカスタム拡張ツールも操作を委任しない限り、ホスト上で引き続き実行されます。

Gondolin

Gondolin はローカル Linux マイクロ VM です。ホスト上で 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

この拡張機能は、VM の /workspace にホスト cwd をマウントし、read、write、edit、bash、grep、find、ls をオーバーライドします。ユーザー ! コマンドも VM にルーティングされます。 /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 のコンテナにマウントします。これにより、Gondolin の例のように、Docker 内の /workspace での読み取りと書き込みがホストファイルに直接影響します。

コンテナローカルの設定とセッションが必要な場合は、/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 を呼び出すことができ、ゲートウェイは構成されたプロバイダーの資格情報を上流に挿入します。モデルのトラフィックにこのルートを使用させる場合は、対応する OpenAI 互換または Anthropic 互換のエンドポイントを使用するように Pi を構成します。