OpenShell Plus

OpenShell とは何か

NVIDIA OpenShell は、自律的に動作する AI エージェント（agent の集合体）を カーネルレベルの隔離されたサンドボックスで実行するためのオープンソース・ランタイムです。 エージェントにはファイル読み書き・パッケージ導入・API 呼び出し・クレデンシャル利用といった 能力を与えつつ同時に、あなたのデータ・シークレット・ネットワークへの無制限アクセスは渡さない。 何に触れてよいかを policy（宣言的 YAML）で記述し、OpenShell がそれを強制します。

なぜ必要なのか

エージェントは「ファイルを読めて、パッケージを入れられて、API を呼えて、鍵を使える」ときに初めて実用的になります。 同じアクセスが、そのまま実データ窃取・情報漏えいの経路にもなり得ます。OpenShell はこのトレードオフを 能力を保ちつつ、アクセスを明示的に制御することで解きます。

2 つの軸で統制する

脅威と対策

多層防御（どの層がいつ効くか）

agent は本物のクレデンシャルを一切見ません。OpenShell が承認済み宛先宛のリクエストにだけ資格情報を付与します。

構成要素

OpenShell の中心は gateway（コントロールプレーン）です。sandbox を作ると、compute driver が workload と独立した supervisor を用意し、両者の保護されたチャネルを張って隔離境界を構築します。 supervisor が境界を確認したうえで agent を起動し、以後は gateway に policy・クレデンシャル・ログ・対話セッションを要求します。

ネットワーク要求の流れ

1. エージェントが TCP 接続を開き、または DNS 照会を行う
2. sandbox が呼び出し元のプログラムを特定する（/proc の信頼できる観測）
3. 要求が Sandbox Protocol 経由で supervisor へ渡る
4. supervisor が policy と照合し、policy が認めるクレデンシャルを付与する
5. 許可された場合のみ、supervisor が実際の接続を開いて中継する

ランタイムごとの境界の作り方

supervisor と sandbox は OpenShell Sandbox Protocol で対話します。相互認証された 1 本の HTTP/2 接続が 多数の独立したストリームを運びます（制御・DNS・接続ごとの TCP）。compute driver が transport を選びますが （Docker/Podman は Unix socket、Kubernetes は TCP、MicroVM は vsock）、認証とプロトコルの挙動はすべて同一です。 接続ごとの独立 backpressure があるため、遅いダウンロードが DNS や exec を塞ぎません。

コンポーネント間の認証

gateway だけが資格情報を署名し、すべての資格情報はちょうど 1 つの sandbox のみを指します。sandbox の 1 回の実行ごとに gateway が JWT のペアを発行します。

両方の JWT は sandbox とその 1 回の実行（generation）に束縛されます。sandbox を再起動すると新しい generation になり、 新しいトークンと新しい TLS 証明書が発行され、古いものは失効します。supervisor が切断されると sandbox は agent を 凍結し、同じ supervisor プロセスだけが再接続して再開できます（有効なクレデンシャルを持つ別 supervisor への乗っ取りは不可）。

結果として、agent 側には盗む価値のあるものがありません。gateway の署名鍵、gateway JWT、provider クレデンシャルは 一切 sandbox 側に置かれません。

OpenShell に入る（最小手順）

# Linux / Apple Silicon の macOS / WSL2（experimental）+ Docker / Podman / ホスト仮想化が必要
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
openshell status
openshell sandbox create --name demo

インストーラが CLI とローカル gateway をセットアップします。既定の sandbox イメージは agent 未インストールの最小 Ubuntu です。 実際の agent（OpenCode など）を動かす場合は model provider の設定と policy 承認の方法が別途必要です。 詳細は 公式ドキュメント と GitHub リポジトリ を参照してください。

何ができるか

OpenShell の sandbox は「隔離された実行環境」です。openshell-plus はそのライフサイクルを HTTP API と WebSocket コンソールにマッピングし、CLI と同じ操作をブラウザの画面から行えるようにします。

4 つのデプロイ形態

同じアプリケーションを、用途に応じて 4 通りの形で公開できます。構成は OSUI_MODE と起動方法だけで切り替わります。

Colab で 3 ステップ・clone 不要

ブラウザだけでデモを動かせます。ローカルへの clone もビルドも不要です。GPU ランタイムでも同じ手順で動きます。

• ノートブック deploy/colab/openshell_colab.ipynb — 同じノートブックを全環境で使えます。用途別のレシピは USAGE.md を参照してください。
• 公開トンネルは使いません。 Colab の FAQ は、インタラクティブな計算と無関係な Web サービス提供、および無料枠での「ノートブック UI を迂回して Web UI を主眼として操作すること」およびリモートプロキシへの接続を禁じています。恒久トンネルは VM リセットで切れ、アイドルでランタイムも終了します。

構成図

ブラウザ → FastAPI → backend → OpenShell gateway → 隔離境界という操作の流れと、 supervisor と sandbox の分界を 1 枚にまとめたものです（下の図はインタラクティブに操作できます: クリックで選択、テーマ切替、拡大縮小、PNG / SVG 書き出しに対応）。 このページの配色に合わせたライトテーマで埋め込んでいます。図のツールバーから ダークテーマに切り替えることもできます。「全画面で開く」で単独表示した際は、 保存済みの設定または端末の設定が優先されます。

全画面で開く

core/factory.py が起動時に gateway へ health で接続を試み、到達できなければ demo backend にフォールバックします。 Vercel や Colab のように実 gateway に到達できない環境でも、demo backend にフォールバックすることで、UI が落ちないようにするための設計です。

クイックスタート（ローカル）

git clone https://github.com/watanabe3tipapa/openshell-plus.git
cd openshell-plus
uv sync --all-extras

# OpenShell CLI が未導入の場合
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
openshell status

# 実際に gateway へ接続する場合
export OSUI_GATEWAY_ENDPOINT=https://localhost:17670
./scripts/run-local.sh
# → http://127.0.0.1:8080

目的別の活用レシピ、コンソールの制約（パイプやリダイレクトが効かない点など）、トラブルシューティングは USAGE.md にまとめています。

環境変数

ガイドの訂正点（実 API との差分）

ガイドの擬似コードがそのまま実装できなかった箇所を、実 SDK の仕様に合わせて整理しました。コードを書くときの注意点は以下です。

• SandboxSession(client, sandbox_id) は存在しません。client.create(...) が SandboxRef を返します。
• get / list / delete / exec は name と workspace で識別します。UUID 直接指定は不可。
• status.phase は文字列ではなく enum（int）。UI 側で phase_label() に渡して日本語へ変換します。
• イメージは --from で明示します。既定値は nvcr.io/nvidia/base/ubuntu:24.04。
• サービス公開は service expose <name> <port> [service]。削除は service delete です（unexpose ではない）。
• ローカルアクセスには openshell forward start 8000 my-sandbox が使えます。tunnel 不要で localhost へフォワードできます。
• provider プロファイルは openshell profile import --url <URL> で投入します。inference set のようなコマンドは存在しません。

セキュリティ

• loopback 以外の bind ではトークンを必須とし、起動時に検証します。
• token は Authorization: Bearer、Sec-WebSocket-Protocol: bearer.*、?token= の 3 経路を受け付けます（WebSocket はヘッダ制約のため bearer.* を使用）。
• mTLS と OIDC は gateway の要件に合わせて個別に有効化します。非 loopback gateway では TLS 必須です。
• 静的アセットは token なしで配信されます。機密情報は含まれません。
• Colab からの公開トンネル接続はデフォルトで無効（ポリシー違反のため）。

リポジトリ構成