Pi Agent のセキュリティとプロジェクト信頼
Pi Agent は現在のユーザーの権限で実行されます。
この章では、プロジェクト信頼メカニズム、セキュリティ境界、コンテナ化実行方法について説明します。
Pi Agent のセキュリティモデル
Pi Agent はローカルコーディングエージェントです——起動した時点のユーザー権限で実行され、ファイルの読み取り、書き込み、編集、およびシェルコマンドの実行ができます。
これはつまり：
- あなたのユーザーアカウントがアクセスできるすべてのファイルにアクセスできます
- 実行できるコマンドの範囲は、ターミナルで手動で操作する場合と完全に同じです
- 它組み込みのサンドボックス分離メカニズムはありません
これは意図的な設計です。Pi Agent はプロジェクトのツールチェーンを呼び出し、テストを実行し、依存関係をインストールする必要があり、これらの操作には実際のシステム権限が必要です。
Pi Agent の設計哲学は、「一見安全そうで実際には誤解を招きやすい」中途半端なサンドボックスを提供しないことです。
真の分離は、オペレーティングシステムレベルまたは仮想化/コンテナ境界からもたらされるべきです。
プロジェクト信頼メカニズム
プロジェクト信頼（Project Trust）は、Pi Agent がプロジェクトローカルの設定と拡張機能を読み込むかどうかを制御します。
これはサンドボックスではありません。制御するのは起動時に何を読み込むかだけで、モデルが対話中に何ができるかを制限するものではありません。
どのような場合に信頼チェックがトリガーされるか
Pi Agent がプロジェクトディレクトリ内で以下のいずれかを検出すると、信頼チェックがトリガーされます：
- .pi/settings.json（プロジェクト設定ファイル）
- .pi/extensions、.pi/skills、.pi/prompts、.pi/themes（プロジェクトリソースディレクトリ）
- .pi/SYSTEM.md または .pi/APPEND_SYSTEM.md（プロジェクトシステムプロンプト）
- .agents/skills（プロジェクト Skills ディレクトリ）
.pi の空ディレクトリのみでは、信頼チェックはトリガーされません。
信頼決定プロセス
Pi Agent は、固定された順序で現在のプロジェクトのリソースを読み込むかどうかを判断します。
- trust.json に保存済みの決定があるかどうかを確認します（現在のディレクトリから上方向に検索）
- ある場合は、保存済みの決定を使用します
- ない場合は、defaultProjectTrust 設定の動作に従います（デフォルト：ask、つまり確認）
- ユーザーは決定を下した後、「記憶する」を選択でき、trust.json に書き込まれます
信頼決定はディレクトリごとに、グローバルの ~/.pi/agent/trust.json に保存されます。
検索時は親ディレクトリを順にさかのぼってそのファイルにマッチさせます。保存済みの決定が何も見つからない場合にのみ、defaultProjectTrust のロジックが使用されます。
信頼されていないプロジェクトに初めて入ると、画面に以下のプロンプトが表示されます：
检测到项目本地配置 .pi/settings.json 是否信任此项目并加载其配置与扩展？(y/n/always/never)
プロンプトの文言とオプションはバージョンによって異なる場合があります。実際の画面を基準にしてください。
プロジェクト信頼は、拡張機能やスキルなどの保護されたリソースの読み込みのみを制御します。
AGENTS.md、CLAUDE.md などのコンテキストファイルは、信頼されているかどうかに関係なく読み込まれます。
defaultProjectTrust 設定
この設定項目は、誰も確認しない場合の Pi Agent のデフォルトの選択肢を決定します。対話モードと非対話モードでは動作が異なります。
| 值 | 対話モードの動作 | 非対話モードの動作 |
|---|---|---|
| "ask"（デフォルト） | 信頼確認プロンプトを表示する | プロジェクトリソースを読み込まない（"never" と同じ動作） |
| "always" | 自動信頼 | 自動信頼 |
| "never" | 自動拒否 | 自動拒否 |
設定方法：
例
"defaultProjectTrust": "always"
}
コマンドライン引数を使用して、単回の動作を上書きすることもできます：
# 本次运行信任项目 $ pi --approve $ pi -a # 本次运行不信任项目 $ pi --no-approve $ pi -na
/trust コマンドを使用して決定を保存する
対話モードでは、/trust コマンドを使用していつでも現在のプロジェクトの信頼決定を保存できます：
/trust
このコマンドは、~/.pi/agent/trust.jsonディレクトリ単位で保存された信頼決定を記録するファイルに書き込みます。
/trust は現在の決定を保存しますが、現在のセッションはリロードされません。
信頼決定を変更した場合は、変更を有効にするために Pi Agent を再起動する必要があります。
非対話モードのセキュリティ考慮事項
Print モード（-p）、JSON モード（--mode json）、RPC モード（--mode rpc）では、Pi Agent は信頼プロンプトを表示しません。
この場合の動作は、defaultProjectTrust 設定に完全に依存します：
- "ask" または "never" に設定：プロジェクトリソースは無視されます
- "always" に設定：プロジェクトリソースが読み込まれます
--approve または --no-approve を使用すると、この動作を一時的に上書きできます。
信頼できないコードの実行
信頼できないリポジトリや自動化タスクを処理する必要がある場合は、コンテナまたはサンドボックス内で Pi Agent を実行することをお勧めします：
- コンテナ方式：pi プロセス全体を Docker コンテナまたは VM 内で実行する
- Gondolin 方式：ホストで pi を実行し、ツールの実行を Gondolin マイクロ VM にルーティングする
- OpenShell 方式：pi プロセス全体を NVIDIA のポリシー制御サンドボックス内で実行し、ゲートウェイを通じてサンドボックスを作成する
- マウント制御：エージェントがアクセスする必要のある作業ディレクトリのみをマウントする
- 認証情報の管理：ホストの ~/.pi/agent/ ディレクトリのマウントを避け、最小権限の一時 API キーを渡す
- ネットワーク分離：タスクがネットワークを必要としない場合は、コンテナのネットワークアクセスを制限する
- 結果のレビュー：出力を信頼されたシステムにコピーして戻す前に、diff と変更内容をレビューする
Gondolin は独立したオープンソースのマイクロ VM プロジェクトです（ローカル Linux マイクロ VM、QEMU サポートが必要）。Pi はサンプル拡張機能を通じて、組み込みツールの実行をそこにルーティングします。
OpenShell はopenshell sandbox create --from piサンドボックスを作成します。事前にゲートウェイを登録して選択する必要があります。
リモートゲートウェイモードではローカルディレクトリを bind-mount しないため、アップロード/ダウンロードコマンドを使用してサンドボックス内外でファイルを転送する必要があります。モデルの認証情報はサンドボックスの外に置いたままにできます。
ホストの作業ディレクトリを読み書き可能な状態でコンテナにバインドマウントすると、コンテナ内の書き込み操作は依然としてホストのファイルに影響を与えます。
より厳格な保護が必要な場合は、読み取り専用マウントを使用するか、ファイルをサンドボックスとの間でコピーしてください。
セキュリティのヒント
以下に、一般的な使用シナリオに応じたセキュリティの推奨事項を示します。作業を始める前に、照らし合わせて確認してください。
| シナリオ | 推奨事項 |
|---|---|
| サードパーティコードのレビュー | コンテナで実行し、読み取り専用マウントを使用する |
| 自動化 CI/CD | 一時的な認証情報を使用し、ツールのホワイトリストを制限する |
| チーム共有設定 | プロジェクトの .pi/settings.json を使用するが、機密情報は入れない |
| サードパーティの拡張パッケージのインストール | ソースコードをレビューしてからインストールする。拡張機能は任意のコードを実行できる |
| サードパーティの Skills のインストール | SKILL.md の内容をレビューする。Skills はモデルに任意の操作を指示できる |