openshell-cli

OpenShell CLI

サンドボックスとプラットフォームを管理するための openshell CLI の使い方をエージェントに説明します。基本操作から高度な複数ステップのワークフローまでを扱います。

概要

OpenShell CLI（openshell）は、サンドボックス、プロバイダー、ポリシー、設定、公開サービス、ゲートウェイ登録を管理するための主要なインターフェイスです。ゲートウェイサービスのライフサイクルは、パッケージ、systemd、または Helm によって CLI の外部で処理されます。このスキルでは、一般的なワークフローや複雑なワークフローで CLI コマンドをオーケストレーションする方法を説明します。

関連スキル：サンドボックスポリシーの YAML コンテンツ（ネットワークルール、L7 検査、アクセスプリセット）を作成または変更する場合は、generate-sandbox-policy スキルを使用してください。このスキルではポリシーのライフサイクルに関する CLI コマンドを扱い、generate-sandbox-policy ではポリシーのコンテンツ作成を扱います。

自己学習：CLI には包括的な組み込みヘルプがあります。このスキルで扱っていないコマンドやオプションに遭遇した場合は、ヘルプツリーをたどってください。

openshell --help                    # Top-level commands
openshell <group> --help            # Subcommands in a group
openshell <group> <cmd> --help      # Flags for a specific command

これが主なフォールバック手段です。気軽に活用してください。CLI のヘルプ出力は信頼できる情報源であり、常に最新です。

前提条件

• openshell が PATH 上にあること。インストールされていない場合は、公開されているインストールガイドに従ってください。
• Docker、Podman、Kubernetes、または実験的な VM ドライバーを利用する、到達可能な OpenShell ゲートウェイ
• BYOC のローカルビルドまたは Docker を利用するゲートウェイを使用する場合に限り、Docker が実行中であること
• Kubernetes デプロイの場合：対象クラスターへの kubectl と Helm のアクセス

信頼できるリファレンス

インストールされている CLI バージョンについては、openshell --help とネストされた --help の出力を正式な情報源として使用してください。製品の概念やサポート対象のワークフローについては、公開ドキュメントを使用してください。

• ゲートウェイの管理
• サンドボックスの管理
• プロバイダーの管理
• プロファイル
• サンドボックスポリシー
• 推論ルーティング

---

ワークフロー 1：はじめに

ゲートウェイのエンドポイントがあり、初めてサンドボックスを起動したい場合は、このワークフローを使用してください。

ステップ 1：ゲートウェイを登録する

openshell gateway add http://127.0.0.1:8080 --local --name local

http:// エンドポイントは、信頼できるローカルのポートフォワーディング、または保護されたプライベート経路でのみ使用してください。認証済みリバースプロキシの背後にゲートウェイがある場合は、HTTPS エンドポイントを openshell gateway add https://gateway.example.com で登録してください。

ステップ 2：ゲートウェイを確認する

openshell status
openshell whoami

ゲートウェイに到達でき、認証が有効または不要であり、出力にバージョンが表示されることを確認してください。Status: Connected が示すのは、公開ヘルスエンドポイントに到達できることだけです。保護されたコマンドを実行する前に、独立した Authentication の行を確認してください。openshell whoami はゲートウェイによって検証された ID を報告します。これには、管理者がワークスペースのメンバーシップに使用するサブジェクトも含まれます。自動化する場合は --output json を追加してください。

ステップ 3：サンドボックスを作成する

サンドボックスを起動する最も簡単な方法は次のとおりです。

openshell sandbox create

これにより、標準のメインプロセスが /bin/bash -l のサンドボックスが作成され、保持されたそのプロセスにターミナルが接続されます。サンドボックスの準備が完了した時点で接続せずに戻るには、--detach を追加します。

末尾に明示的なコマンドを指定した場合、stdin または stdout がターミナルでなくてもフォアグラウンドで実行されます。CLI は stdout と stderr をストリーミングし、出力の処理が完了した後にコマンドの終了ステータスを報告します。出力を配信できないと、コマンド自体が正常に終了していても CLI は失敗を報告します。副作用が発生する可能性のある作業を再試行する前に、サンドボックスの状態を確認してください。終了コードが 0 の場合、保持されたサンドボックスは Completed になります。0 以外の場合は MainProcessFailed を伴って Error になります。出力の処理後にどちらの結果も削除するには --no-keep を使用し、長時間実行されるサービスには --detach を使用してください。ゲートウェイでホストに接続せずにサービスを実行し、サービスの終了後にそのサンドボックスを削除するには、--detach --no-keep を組み合わせます。

--name を指定する場合は、移植可能な DNS-1123 ラベルを使用してください。63 文字以下の小文字英数字または - で構成し、先頭と末尾は英数字にする必要があります。Kubernetes ドライバーは、大文字、アンダースコア、ドット、および Kubernetes リソースラベルとして使用できないその他の名前を拒否します。

プロバイダーへの接続は明示的に指定します。各プロバイダーには --provider で名前を付けてください。末尾のコマンドによってプロバイダーが選択されたり、接続されたりすることはありません。指定したプロバイダーが存在せず、その ID のプロファイルが利用可能な場合、CLI はローカルの認証情報からプロバイダーを作成できます。

openshell sandbox create --from registry.example.com/your-org/claude-agent:latest --provider claude-code -- claude
openshell sandbox create --from registry.example.com/your-org/codex-agent:latest --provider codex -- codex

認証情報がない場合、エージェントは対話形式で入力を求めます。

ステップ 4：終了してクリーンアップする

exit でサンドボックスのシェルを終了するか、Ctrl-D でデタッチしてから、次を実行します。

openshell sandbox delete <name>

---

ワークフロー 2：プロバイダーの管理

プロバイダーは、サンドボックスに認証情報とプロバイダー固有の設定を提供します。プロバイダープロファイルはインポート専用です。ゲートウェイが提供するのはオペレーターがインポートした内容そのものであり、新しいゲートウェイのカタログは空です。ハードコードされたタイプの一覧や、gh、claude のような旧式のエイリアスには依存しないでください。--type はプロファイル ID と完全一致します。選択したゲートウェイで利用可能なプロファイルを確認します。

openshell profile list
openshell profile list --type provider --output json

ローカルの認証情報からプロバイダーを作成する

openshell provider create --name my-github --type github --from-existing

--from-existing フラグは、ローカルの状態から認証情報を検出します（例：gh auth のトークン、Claude の設定ファイル）。

明示的な認証情報を使用してプロバイダーを作成する

openshell provider create --name my-openai --type openai \
  --credential OPENAI_API_KEY

値を指定しない KEY は、同じ名前の環境変数から値を読み取るため、シェルの履歴にシークレットが残りません。KEY=VALUE を使用するのは、ユーザーがその露出を明示的に了承した場合に限ってください。

その他の認証情報ソースには、互換性のあるプロファイルで使用する --from-gcloud-adc と、ゲートウェイまたはサンドボックスが実行時に必要な認証情報を解決する場合に使用する --runtime-credentials があります。

静的なプロバイダー認証情報は、プロバイダープロファイルで宣言されたホスト、ポート、パスに対してのみ解決されます。プレースホルダーが存在するのにリクエストが credential_endpoint_mismatch を受け取る場合は、profile export を使ってこの範囲を確認してください。プロファイルのない静的プロバイダーは、ゲートウェイがバインディングを構築できないため、フェイルクローズで失敗します。

検査対象のリクエストが request_authority_mismatch を受け取る場合は、その HTTP authority を CONNECT トンネルのエンドポイントと比較してください。ホストと実効ポートが一致している必要があります。api.example.com:8443 へのトンネルでは、Host: api.example.com:8443 を送信してください。Host: api.example.com はデフォルト以外のポートを省略しているため、拒否されます。絶対形式のリクエストターゲットでも、同じ authority を使用する必要があります。

プロファイルに基づくプロバイダーは、ゲートウェイ全体に適用されるポリシーが有効でない限り、常にポリシーを適用します。静的な認証情報のエンドポイントバインディングは、これとは独立して引き続き適用されます。

プロバイダーにラベルを付けて選択する

プロバイダーの作成時に、繰り返し指定できる --label KEY=VALUE フラグを使ってラベルを付けます。ラベルは各認証情報ソースで使用できます。リストセレクターでは、カンマ区切りのすべてのキーと値のペアが一致する必要があり、ページネーションの前に適用されます。

openshell provider create --name public-pypi --type pypi --label env=dev --label team=ml
openshell provider list --label-selector env=dev,team=ml
openshell provider list --all-workspaces --label-selector team=ml --output json
openshell provider get public-pypi

この例の pypi のように、インポートしたプロファイルを使用します。get ではラベルが表示され、構造化リスト出力にはラベルが含まれます。--all-workspaces には Platform Admin アクセスが必要です。次の --page-token を渡す際は、セレクターとワークスペースのスコープを維持してください。プロバイダーの作成後は、ラベルを変更または削除できません。

プロバイダープロファイルを確認して管理する

openshell profile describe github
openshell profile export github --output yaml
openshell profile lint --file ./my-profile.yaml
openshell profile import --file ./my-profile.yaml
openshell profile lint --url https://example.com/profiles/my-profile.yaml
openshell profile import --url https://example.com/profiles/my-profile.yaml

--url には、HTTP または HTTPS の YAML または JSON プロファイルを1つ指定できます。インポートする前に、エンドポイントとバイナリの許可設定を確認してください。URL のパスは .yaml、.yml、または .json で終わる必要があります。ダウンロードの上限は 1 MiB、タイムアウトは 15 秒です。

profile describe を使用すると、プロバイダーを作成する前に、定義の認証情報メタデータ、エンドポイント、TLS の処理、MCP アクセス設定、ルール数、バイナリ、ソース、スコープを確認できます。表示された L7 ルールを信頼する前に、tls: skip と、未検査の認証情報を許可するオプトイン設定を確認してください。リストと詳細表示では、テーブル、JSON、YAML の出力を指定できます。ルール定義をすべて確認するには構造化出力を、ワークスペースのカタログには --workspace を、プラットフォームのスコープには --global を使用してください。編集可能な定義を準備するには profile export を、既存のカスタムプロファイルを現在のリソースバージョンで置き換えるには profile update <id> --file <file> を、カスタムプロファイルを削除するには profile delete <id>... を使用してください。プロバイダーインスタンスは引き続き provider の下にあります。

既存のスクリプトでは、引き続き provider list-profiles と provider profile export/import/update/lint/delete を使用できます。これらのコマンドはトップレベルのハンドラーを共有し、引数、出力オプション、ワークスペース／グローバルフラグをそのまま維持します。新しいコマンドを作成する際は、profile を優先してください。

一覧表示、確認、更新、削除

openshell sandbox provider status --help と attach、detach、update のヘルプを確認し、インストール済みバージョンで利用できる待機オプションを調べてください。プロバイダーの変更が反映されてから次の手順に進む必要がある場合は、--wait を追加してください。これを指定しない場合、コマンドの成功で確認できるのは、ゲートウェイが変更を保存したことだけです。返された receipt_id を保存し、後で同じ変更を確認してください。選択したサンドボックスごとに結果を確認します。認証情報の更新ステータスでは、OpenShell が認証情報を取得したことを確認できます。プロバイダーのステータスでは、サンドボックスが認証情報を適用し、ポリシーを有効化し、新しいプロセス向けに環境を更新したことを確認できます。ステータスが superseded の場合は、後続の変更によってリクエストが置き換えられたことを説明し、その変更を個別に確認してください。

attach、detach、または update が CONFIG_OPERATION_STORAGE_UNCERTAIN を報告した場合、変更はすでに保存されている可能性があり、準備完了レシートを利用できないことを説明してください。変更をむやみに再試行しないでください。別の変更を行うか判断する前に、プロバイダーとサンドボックスの状態を確認し、保存済みの変更を照合してください。このエラーから、ロールバックも準備完了も確認できません。

openshell provider list
openshell provider list --output json
openshell provider get my-github
openshell provider update my-github --from-existing
openshell provider delete my-github

provider update は --type を受け取りません。既存のプロバイダーの認証情報、設定、または認証情報の有効期限を更新します。

外部のアップデーターで、ワークロードが元の環境参照を維持する必要がある場合は、stable_placeholder: true を指定した認証情報プロファイルと、そのモードをサポートするゲートウェイおよびスーパーバイザーを使用してください。CLI はオプトインをインポートまたは更新する前に、ゲートウェイのサポート状況を確認します。デフォルトは引き続き false であり、既存のリビジョン単位の動作と通常のレガシーゲートウェイの運用が維持されます。スーパーバイザーが発行した値をそのまま保持してください。プレースホルダーを自分で作成してはいけません。スーパーバイザーが値のみの更新をインストールした後、保持された参照は、有効なホスト、ポート、パスのバインディングに限り、現在の認証情報を解決します。置き換え、有効期限切れ、バインディングの変更、または有効化された detach によって、古い権限は解決されなくなります。ゲートウェイをダウングレードする前に、オプトインを削除して変更を有効化してください。ライフサイクルの契約、およびゲートウェイ管理の更新や token_grant との分離については、プロバイダープロファイルのドキュメントを参照してください。

認証情報の更新を設定する

プロバイダープロファイルとゲートウェイが更新可能な認証情報に対応している場合にのみ、更新コマンドを使用してください。

openshell provider refresh status my-provider
openshell provider refresh configure my-provider \
  --credential-key MS_GRAPH_ACCESS_TOKEN \
  --strategy oauth2-refresh-token \
  --secret-material-env REFRESH_TOKEN=MS_GRAPH_REFRESH_TOKEN \
  --credential-expires-at 2026-07-16T00:00:00Z
openshell provider refresh rotate my-provider --credential-key ACCESS_TOKEN

シークレットの更新用データには、--secret-material-env KEY[=ENVVAR] を優先して使用してください。--material KEY=VALUE はシークレットではないデータ用です。--secret-material-key は、指定したデータのキーをシークレットとして扱うよう指定します。

ゲートウェイは、アクティブな認証情報ドライバーを通じてシークレットの更新用データを保存します。 Vault が選択されている場合、更新トークン、クライアントシークレット、秘密鍵は、注入可能なプロバイダー認証情報とともに Vault に保存されます。更新状態には、不透明なハンドルのみが含まれます。認証情報バックエンドの読み取りまたは書き込みに失敗した場合、インラインストレージにフォールバックせず、更新はフェイルクローズします。OpenShell 0.1.0 より前のバージョンでは、 ゲートウェイは従来のインライン更新用データを移行せず、シークレットを認証情報バックエンド間で移動しません。アップグレード後に該当する許可を再設定してください。また、バックエンドを変更する前に、元のバックエンドが利用可能な状態で認証情報を削除するか、再設定してください。同じ更新レコードに対して、異なるゲートウェイバージョンを混在させて実行しないでください。

ゲートウェイ管理の更新用認証情報では、ID が安定したワークロードハンドルを使用します。 通常の自動更新と provider refresh rotate は、そのハンドルの背後にあるアクセストークンを更新するため、長時間稼働するプロセスを再起動する必要はありません。リビジョン単位のプレースホルダーからアップグレードする場合は、実行中のプロセスを一度再起動する必要があります。それ以降に provider refresh configure を実行すると、明示的な再認証の境界となり、以前のハンドルは無効になります。そのハンドルを保持しているプロセスは、再起動されるまでフェイルクローズします。

ゲートウェイ管理の更新が設定されている間は、provider update --credential で、更新管理対象のプライマリ認証情報や、同時に生成された出力を置き換えたり削除したりすることはできません。これらのキーを手動管理に戻すには、provider refresh rotate を使用するか、更新を再設定するか、更新を削除してください。無関係なプロバイダーフィールドは引き続き更新できます。

OAuth の更新に失敗した場合は、provider refresh status の RECOVERY 列と FAILURE_CODE 列を確認してください。HTTP ステータスから対処方法を推測したり、LAST_ERROR を解析したりしないでください。retry はワーカーが再試行することを意味します。reauthorize は、ユーザーが新しい OAuth 許可を取得して provider refresh configure を実行する必要があることを意味します。fix_configuration は、オペレーターが OAuth クライアント、スコープ、または管理者ポリシーを修正する必要があることを意味します。investigate は、認識できない発行者の応答や、結果が不確かな状態で中断された生成処理を示す場合があります。ゲートウェイは reauthorize のレコードを、手動でローテーションまたは再設定されるまで保留します。外部で修正された設定がトークンエンドポイントへの過剰なアクセスなしに反映されるよう、fix_configuration のレコードは1時間ごとに再試行されます。既存のアクセス認証情報は、記録された有効期限までは引き続き使用できます。

refresh_in_progress と refresh_committing は、処理が進行中であることを示す場合があります。これらを失敗と判断する前に、ゲートウェイの健全性と更新状態を再確認してください。並行する更新リクエストは、進行中の生成処理が完了するまで待機します。ゲートウェイの中断によっていずれかのマーカーが残り、ローテーションで前回の生成結果が不確かであると報告された場合、ゲートウェイはその許可を自動的に再利用しません。発行者の状態を調査してから、有効な許可を使って provider refresh configure を実行してください。前回の更新トークンが消費された可能性がある場合は、まず新しい OAuth 許可を取得してください。マーカーを直接消去したり、繰り返しローテーションしたりしないでください。再設定すると古いワークロードハンドルが無効になるため、それらを保持しているプロセスを再起動してください。

---

ワークフロー 3：サンドボックスのライフサイクル

オプションを指定して作成

openshell sandbox create \
  --name my-sandbox \
  --provider my-github \
  --provider my-claude \
  --policy ./my-policy.yaml \
  --label team=agents \
  -- claude

主なフラグ：

• --provider：API キー、トークン、その他のシークレット用に、設定済みの認証情報プロバイダーを接続します（複数回指定可能）
• --policy：カスタムポリシー YAML（指定しない場合は、組み込みのデフォルトまたは OPENSHELL_SANDBOX_POLICY 環境変数が使用されます）
• --gpu [COUNT]：ドライバーのデフォルトの GPU 選択または特定の GPU 数を要求します
• --cpu、--memory：サンドボックスごとのコンピューティングリソースを設定します。Docker／Podman では上限が適用され、Kubernetes では対応するリクエストと上限が適用されます。
• --driver-config-json：実験的なドライバー固有のサンドボックス設定を渡します
• --template NAME：名前付きのサンドボックスワークロードテンプレートから作成します。--from、--gpu、--cpu、--memory、--env、--env-from、--driver-config-json などのインラインワークロードフラグとは併用できません。
• --label KEY=VALUE：後で選択するためのラベルを追加します（複数回指定可能）
• --annotation KEY=VALUE：ファイルパスなどのシークレットではないメタデータを追加します（複数回指定可能）
• --env KEY=VALUE：シークレットではないサンドボックス環境変数を設定します（複数回指定可能）。認証情報には --provider を使用してください
• --env-from KEY[=ENVVAR]：値を引数に含めずに、CLI プロセスの環境からサンドボックス環境変数の値を読み込みます。認証情報をワークロードから隠すには --provider を使用してください
• --tty：正規のメインプロセス用に保持される PTY を割り当てます
• --restart-policy never|on-failure|always：ゲートウェイが管理するメインプロセスの再起動動作を選択します。デフォルトは never です
• --approval-mode manual|auto：エージェントが作成したポリシー提案の処理方法を制御します。デフォルトは manual です
• --upload <PATH>[:<DEST>]：ローカルファイルをコンテナーの作業ディレクトリまたは明示した宛先にアップロードします
• --no-git-ignore：アップロード時の .gitignore によるフィルタリングを無効にします
• --no-keep：メイン出力と終了結果の取得後にサンドボックスを削除します
• --detach：接続せずに正規のメインプロセスを起動します
• --forward [BIND_ADDRESS:]PORT：ローカルポートを転送し、サンドボックスを稼働状態に保ちます
• --editor vscode|cursor：作成後にリモートエディターを開き、サンドボックスを稼働状態に保ちます

ドライバーが作成時の検証でフォアグラウンド接続を拒否する場合は、--detach を使用してください。

--detach はアタッチ猶予期間を追加しません。正規のプロセスが終了すると、 そのターミナルフェーズが直ちに報告されます。フォアグラウンドでの作成では、 予期されるメインプロセスの SSH 接続が 1 つ宣言されます。クリーンアップは、その接続が 自然に閉じた後に完了します。--detach --no-keep を指定すると、ゲートウェイが デタッチされたプロセスのライフサイクルを管理し、ターミナル状態の報告が 完了した後にエフェメラルサンドボックスを削除します。

--upload を末尾のメインコマンドと組み合わせないでください。アップロードは現在、 正規のプロセスの起動後に完了します。一時的なサンドボックスを作成して sandbox exec を使用するか、ファイルをイメージに組み込んでください。

複数のサンドボックスでイメージ、環境、リソース設定、またはドライバー固有の設定を 共有する場合は、再利用可能なワークロードテンプレートから作成してください。

openshell sandbox template create gpu-kata \
  --image registry.example.com/agents/python:latest \
  --cpu 2 \
  --memory 4Gi \
  --gpu 1 \
  --driver-config-json '{"kubernetes":{"pod":{"node_selector":{"pool":"gpu"}}}}'

openshell sandbox create --name my-sandbox --template gpu-kata --provider my-github -- claude

ドライバー設定はデフォルトで無効になっています。これらのテンプレートおよび単発の sandbox create --driver-config-json の例を使用するには、管理者が選択したドライバーに対して allow_driver_config = true を設定する必要があります。これはリソースの許可判定を 免除するものではありません。外部アタッチメントには、サンドボックスのラベルではなく、 実際のリソース上に管理者が制御する承認ラベルが必要です。GPU デバイスのアタッチメントは 一時的にラベルの要件が免除されます。公開されている --gpu フラグにはドライバー設定の オプトインは必要ありません。許可設定を変更する前に、公開されているゲートウェイ設定の リファレンスを確認してください。拒否を回避するために許可判定を無効にすることは 推奨しないでください。再利用する場合に限り、ドライバー設定をテンプレートに含めてください。

サンドボックスワークロードテンプレートを管理する

openshell sandbox template create gpu-kata \
  --image registry.example.com/agents/python:latest \
  --cpu 2 \
  --memory 4Gi \
  --gpu 1 \
  --label team=runtime \
  --env FEATURE_FLAG=on
openshell sandbox template list
openshell sandbox template list --label-selector team=runtime
openshell sandbox template list --all-workspaces --output json
openshell sandbox template get gpu-kata
openshell sandbox template delete gpu-kata

テンプレートの --image には OCI イメージ参照を指定できます。省略した場合、 ゲートウェイはそのテンプレートからサンドボックスを作成する際に、デフォルトの サンドボックスイメージを適用します。作成時のポリシー、プロバイダー、ラベル、アップロード、 ポート転送、エディターの起動、および初期コマンドは、sandbox create で指定します。

サンドボックスの一覧表示と確認

openshell sandbox list
openshell sandbox list --selector team=agents --output json
openshell sandbox get my-sandbox

サンドボックス名を省略できるコマンドの多くは、最後に使用したサンドボックスを使います。自動化では明示的な名前を指定してください。

実行中のサンドボックスに接続する

openshell sandbox connect my-sandbox
openshell sandbox connect my-sandbox --editor vscode

サンドボックスの既存の標準メインプロセスに接続します。切断してもそのプロセスは実行を続け、再接続すると同じプロセスインスタンスを対象にして、直近の出力を再生します。確立済みの SSH トランスポートが中断された場合（たとえば、ノートパソコンがスリープしてから復帰した場合）、CLI は一時的な障害に対して最大 60 秒間再試行し、同じプロセスに再接続します。新しいシェルを起動するには、sandbox exec --tty -- /bin/bash -l を使用してください。メインプロセスを終了せずに切断するには、Ctrl-D または Ctrl-P の後に Ctrl-Q を押します。OpenSSH の ~. エスケープはトランスポートの切断として扱われ、自動復旧が開始されます。再接続された後、終了するには Ctrl-D または Ctrl-P の後に Ctrl-Q を押すか、再試行の合間に Ctrl-C を押して復旧をキャンセルしてください。標準入力を所有している場合、Ctrl-C はフォアグラウンドプロセスを中断します。読み取り専用の接続では、Ctrl-C または Ctrl-D を押すとビューアーが終了しますが、メインプロセスや他の接続は実行を続けます。VS Code Remote-SSH は次のように設定してください。

openshell sandbox ssh-config my-sandbox >> ~/.ssh/config

書き込み可能な接続時に、別の接続が標準入力を保持していると、attached read-only; retry input after the owner disconnects と表示されます。スーパーバイザーが切断された接続を閉じる前に再接続すると、自動復旧時にこの状態になることがあります。スーパーバイザーは、接続から最後にバイトを受信してから 60 秒後に接続を閉じます。リレーがデータをバッファリングしていた場合、これはネットワーク障害の発生から 60 秒以上経過した後になることがあります。以前の所有者が切断するかタイムアウトした後、次に入力するつもりだった内容を送信してください。標準入力が空いている場合、接続には input enabled と表示され、その入力がプロセスに転送されるため、Enter や y などのプロンプトへの回答で状態を確認しないでください。何も表示されない場合、古い接続がまだ標準入力を保持しています。接続が読み取り専用だった間に送信した入力はプロセスに届かないため、後でもう一度送信してください。Ctrl-C、Ctrl-D、および Ctrl-P の後に Ctrl-Q を押す操作は、引き続き読み取り専用接続を終了させ、入力を有効にはしません。Ctrl-C でプロセスを中断する必要がある場合は、先に入力を有効にしてください。復旧時に正常な所有者から標準入力が取り上げられることはありません。また、明示的に読み取り専用として接続した場合は、読み取り専用のままです。

connect に canonical main process already finished と表示された場合は、sandbox get で結果を確認してください。保留中のフォアグラウンド接続では、状態が Completed または Error であれば、保持された出力を取得できる場合があります。フェーズだけでは接続可能かどうかは判断できません。on-failure の場合にメインプロセスがゼロ以外の終了コードで終了するか、always の場合に終了すると、バックオフとリソースの置き換え中、サンドボックスは Starting に移行します。新しいスーパーバイザーセッションが Ready になると、connect コマンドと exec コマンドは再開します。明示的な sandbox stop は、保留中の再起動をキャンセルします。

ファイルをアップロードおよびダウンロードする

# Upload local files to the sandbox working directory
openshell sandbox upload my-sandbox ./src

# Download a path relative to the sandbox working directory
openshell sandbox download my-sandbox output ./local-output

アップロードでは上限付きストリーミングを使用し、サンドボックスが入力を消費するまで待機します。プロセス入力の 4 MiB の上限は、アップロード全体のサイズ制限ではありません。CLI と、サンドボックスで使用するスーパーバイザーランタイムの両方をアップグレードしてください。古いスーパーバイザーは、ファイルデータが送信される前にアップロードプロトコルを拒否します。アップロードに失敗またはキャンセルすると、宛先に不完全なファイルが残る場合があります。再試行する前に確認するか、部分ファイルを削除してください。

Git の作業ツリー内でのアップロードでは、デフォルトで .gitignore が適用されます。Git によるフィルタリングに失敗した場合、またはファイルが選択されなかった場合は停止します。Git の作業ツリーの外にあることが確認されたソースは、フィルタリングなしでアップロードされ、.gitignore のルールが適用されないことを示す警告が表示されます。フィルタリングを適用するかどうかを判定するには Git が必要です。リポジトリが破損している場合やアクセスできない場合、アップロードは停止します。意図的にフィルタリングせずアップロードするには、--no-git-ignore を指定してください。これは sandbox create --upload にも適用されます。

sandbox create --upload はプロビジョニング前にすべてのアップロードをローカルで検証し、いずれかが拒否された場合はサンドボックスを作成しません。プロビジョニング後に転送が失敗した場合、サンドボックスは稼働したままで、それ以前のアップロードが完了していることがあります。そのサンドボックスに対して sandbox upload で再試行するか、sandbox delete で削除してください。

アップロードでは、リンク先をたどる代わりに、リンク先のないものも含めてシンボリックリンクが保持されます。シンボリックリンクをソースに指定すると、Git によるフィルタリングは適用されず、リンク自体がアーカイブされます。

アップロード先を省略すると、CLI はリモートの作業ディレクトリを検出します。名前付きディレクトリをアップロードすると、同じ名前の既存ディレクトリにマージされ、一致するエントリは上書きされますが、無関係なエントリは削除されません。ダウンロードでは、その作業ディレクトリからの相対パス、または作業ディレクトリ内の絶対パスを指定できます。

非対話型コマンドを実行する

openshell sandbox exec my-sandbox --workdir /workspace -- ls -la
openshell sandbox exec --name my-sandbox --env MODE=test -- cargo test

サンドボックスは位置引数の名前または --name のいずれかで指定し、両方は指定できません。省略すると、最後に使用したサンドボックスが使用されます。-- は必須です。それ以降はすべてリモートコマンドとして扱われるため、--tty などのオプションはその前に指定してください。

sandbox exec は独立した兄弟プロセスを起動し、出力をストリーミングします。標準出力と標準エラーの読み取りが完了し、配信に成功すると、リモートコマンドの終了コードを返します。出力の配信に失敗した場合、コマンドが正常に終了していても、代わりに終了コード 74 を返します。コマンドの終了後、子孫プロセスが継承した出力パイプを 30 秒を超えて開いたままにすると、この失敗が発生します。副作用を伴う作業を再試行する前に、コマンドが実行されたかどうかを確認してください。正規のメインプロセスに接続するには、sandbox connect を使用してください。--env はシークレットではない値にのみ使用してください。API キー、トークン、その他のシークレットを sandbox exec に渡すのではなく、プロバイダーを使用してサンドボックスに認証情報を紐付けてください。

紐付けたプロバイダーを変更する

openshell sandbox provider list my-sandbox
openshell sandbox provider list my-sandbox --output json
openshell sandbox provider attach my-sandbox my-github --wait --timeout 30
openshell sandbox provider status my-sandbox my-github --output json
openshell sandbox provider detach my-sandbox my-github --wait --timeout 30

構造化された紐付け情報の出力には、プロバイダー名、タイプ、認証情報と設定のキー名がソート順で含まれます。認証情報、ハンドル、設定の値は含まれません。

ログを表示する

# Recent logs
openshell logs my-sandbox

# Stream live logs
openshell logs my-sandbox --tail

# Filter by source and level
openshell logs my-sandbox --tail --source sandbox --level warn

# Logs from the last 5 minutes
openshell logs my-sandbox --since 5m

サンドボックスを削除する

openshell sandbox delete my-sandbox
openshell sandbox delete sandbox-1 sandbox-2 sandbox-3   # Multiple at once
openshell sandbox delete --all

deletion accepted は、クリーンアップがまだ保留中であることを意味します。完了したと判断する前に、サンドボックスが消えるまで確認してください。すでに存在しないサンドボックスの削除は成功します。ワークスペースが見つからない場合や、認証に失敗した場合は引き続きエラーになります。別のプロセスが同じ名前のサンドボックスを再作成した可能性がある場合、その名前でやみくもに再試行しないでください。

サンドボックスの停止と起動

stop を使うと、サンドボックスと永続ワークスペースを保持したまま、コンピューティングを停止できます。

openshell sandbox stop [name]
openshell sandbox start [name]

どちらのコマンドも、デフォルトでは最後に使用したサンドボックスを対象にします。stop はバックグラウンド転送を停止し、Stopped になるまで待機します。start は Ready になるまで待機します。停止中または完了状態では、接続、exec、ファイル転送、転送設定、公開サービスを利用できません。保持されている Completed または Error/MainProcessFailed のサンドボックスを起動すると、新しい canonical-main インスタンスが起動し、以前のランタイム世代の SSH セッションは無効になります。保持状態を削除する操作は引き続き delete です。

サンドボックスの SSH ホスト ID は、停止と起動、およびランタイムの再起動後も維持されます。API クライアントはサンドボックスリソースまたは SSH セッション応答から公開フィンガープリントを取得し、サンドボックス ID に紐付けて固定できます。削除したサンドボックスを同じ名前で再作成しても、別の ID が割り当てられます。検証の動作とリリースの互換性については、サンドボックス SSH ドキュメントを参照してください。

停止済みサンドボックスの再起動をサポートするバックエンドでインフラストラクチャの Error が発生した場合は、報告された原因を修正し、sandbox stop を実行して成功するまで待ってから、sandbox start を実行してください。これによりサンドボックスと永続ワークスペースは保持されますが、削除されたリソースやストレージは復元できません。プロビジョニングがタイムアウトした場合は、クリーンアップが完了するまで待ってから、sandbox start を直接実行してください。

サンドボックスの一時停止と再開

コンピューティングドライバーと分離バックエンドが対応しているゲートウェイでは、サンドボックスを一時停止すると、Ready 状態のサンドボックスをメモリ状態を保持したまま凍結できます。

openshell sandbox suspend [name]
openshell sandbox resume [name]

一時停止は Suspended になるまで待機してから、バックグラウンド転送を停止します。一時停止が拒否された場合、転送は実行されたままになります。再開すると、新しいランタイム世代で状態が復元され、Ready になるまで待機します。対応していないゲートウェイでは、一時停止は FAILED_PRECONDITION で拒否されます。保持された状態を復元できない場合、再開は失敗します。その場合は、明示的にクリーンブートするために sandbox start を使用してください。一時停止中のサンドボックスに対する sandbox start、sandbox stop、sandbox delete は、保持されたメモリ状態を破棄します。

---

ワークフロー 4：ポリシー反復ループ

これは最も重要な複数ステップのワークフローです。観測したアクティビティに基づいてサンドボックスポリシーを調整する、緊密なフィードバックサイクルを実現します。

主な概念：ポリシーには、アクティベーション後に変更できない静的フィールド（filesystem_policy、landlock、process）と、2 つの動的フィールド（network_policies、network_middlewares）があります。選択したコンピュートドライバーがライブポリシー更新に対応している場合、サンドボックスを作り直さずに両方の動的フィールドを更新できます。標準のスーパーバイザーを備えていないドライバーは、サンドボックス構成 API を通じてリビジョンを取得し、それらを読み込んだかどうかを報告します。

起動時に ConfigurationInvalid が報告された場合は、openshell sandbox get を確認し、ゲートウェイ経由でポリシー全体またはプロバイダー一式を修復してください。初回アクティベーションではワークロードがまだ起動していないため、この初期修復中は静的フィールドも置き換えられます。以前にアクティベーションされたサンドボックスでは、再起動の許可が保留中または拒否されている間、静的フィールドの制限が維持されます。 ゲートウェイの 300 秒の修復期間が切れる前に検証が成功すれば、そのまま起動が完了します。保存済み構成の実効的な変更と、その構成の最初の読み込み失敗によって、この期間はリセットされます。繰り返し発生した失敗ではリセットされません。ProvisioningTimedOut の後は、保持されたレコードとクリーンアップの状態を確認し、構成を修復して、クリーンアップの完了後に sandbox start を明示的に一度実行してください。CLI の待機タイムアウトは、このゲートウェイの期限とは別です。 公開されているポリシー修復ガイダンスに従い、置き換え／デタッチの構文は、インストール済み CLI のヘルプで現在の内容を確認してください。

protocol が省略されたエンドポイントでは、明示的プロキシの動作が維持されます。明示的な protocol: tcp は、ポリシー DNS と透過的 TCP を要求し、現在は Docker または Podman ランタイムが必要です。対応していないランタイムでは、ネットワーク契約の一部だけを有効にするのではなく、ワークロードの起動前にポリシーが拒否されます。

Create sandbox with initial policy
        │
        ▼
   Monitor logs ◄──────────────────┐
        │                          │
        ▼                          │
  Observe denied actions           │
        │                          │
        ▼                          │
  Pull current policy              │
        │                          │
        ▼                          │
  Modify policy YAML               │
  (use generate-sandbox-policy)    │
        │                          │
        ▼                          │
  Push updated policy              │
        │                          │
        ▼                          │
  Verify reload succeeded ─────────┘

ステップ 1：初期ポリシーでサンドボックスを作成する

openshell sandbox create --name dev --from registry.example.com/your-org/claude-agent:latest --policy ./initial-policy.yaml -- claude

サンドボックスは、反復作業に備えてデフォルトで起動したままになります。初回セッション後にサンドボックスを自動的に削除する場合に限り、--no-keep を追加してください。

ステップ 2：拒否されたアクションのログを監視する

別のターミナルで、またはエージェントとして実行します。

openshell logs dev --tail --source sandbox

DENIED のログ行を探してください。NET:OPEN [MED] DENIED はブロックされた接続を示し、HTTP:<METHOD> [MED] DENIED はブロックされたリクエストを示します。ポリシーイベントは INFO レベルのログレコードなので、--level warn は追加しないでください。ログには次の情報が含まれます。

• 宛先のホストとポート（ブロックされた対象）
• バイナリパス（接続を試みたプロセス）
• 拒否理由（ブロックされた理由）

ステップ 3：現在のポリシーを取得する

set -o pipefail
openshell policy get dev --base | sed '1,/^---$/d' > current-policy.yaml

--base は、プロバイダーによって構成されたエントリーを含まない、編集可能なポリシーを返します。OpenShell は、アタッチされたプロバイダーのルールを個別に構成します。このコマンドは、リビジョンの詳細、--- 行、その後にポリシー YAML を出力します。policy set はリビジョンの詳細を解析できないため、sed の式で YAML のみを残します。--full は実効ポリシーの確認にのみ使用し、policy set の入力には使用しないでください。

Step 4: ポリシーを変更する

current-policy.yaml を編集して、ブロックされたアクションを許可します。**ポリシーの内容を作成する際は、generate-sandbox-policy スキルに委任してください。**このスキルでは、次の項目を扱います。

• ネットワークエンドポイントのルール構造
• L4 と REST、WebSocket、JSON-RPC、MCP L7 のポリシー判断
• アクセスプリセット（read-only、read-write、full）
• TLS 終端の設定
• 適用モード（audit と enforce）
• バイナリの照合パターン
• 順序付きの network_middlewares、ホストの選択、HTTP リクエスト／レスポンスと WebSocket のバインディング、および fail_open または fail_closed の動作

選択したコンピュートドライバーがポリシーのライブ更新に対応している場合、network_policies と network_middlewares は実行時に変更できます。--wait を使って、アクティブなランタイムがリビジョンを読み込んだことを確認してください。ゲートウェイが更新を受け付けたことだけから、ポリシーが適用されたと判断しないでください。filesystem_policy、landlock、または process の変更が必要な場合は、サンドボックスを再作成する必要があります。openshell/regex などの組み込みミドルウェアは、ゲートウェイへの登録は不要です。オペレーターが実行するミドルウェアは、あらかじめ [[openshell.supervisor.middleware]] に登録されている必要があります。この静的な登録を変更するには、ゲートウェイを再起動する必要があります。

ミドルウェアは、実装が該当するバインディングに対応していることを示す場合、HTTP リクエスト、HTTP レスポンス、またはクライアントの WebSocket テキストメッセージを検査できます。組み込みの openshell/regex は、リクエスト本文とクライアントの WebSocket テキストメッセージに対応しています。アタッチ先と失敗時のポリシーを選ぶには generate-sandbox-policy スキルを使い、ミドルウェアの失敗を調査するには debug-openshell-cluster を使ってください。

Step 5: 更新したポリシーをプッシュする

openshell policy set dev --policy current-policy.yaml --wait

ゲートウェイは、直接更新、増分マージ、承認済みの提案、プロバイダーのアタッチ、またはアタッチ済みサンドボックスに影響するプロファイル更新を保存する前に、アタッチされたプロバイダープロファイルのポリシーを含む、有効な候補全体を検証します。あいまいさによる失敗では FAILED_PRECONDITION が返され、拒否された候補によってポリシーのリビジョンが作成されたり、影響を受けるサンドボックスが部分的に更新されたりすることはありません。同じフェイルクローズの応答は、credential_signing にエンドポイントを網羅する認証情報の境界を持つ AWS プロファイルがアタッチされていない場合や、エンドポイントを持たない AWS プロファイルへの明示的なバインディングがある場合にも適用されます。競合するエンドポイントセレクターまたは認証情報ソースを修正して、再度送信してください。

--wait フラグを指定すると、サンドボックスがポリシーの読み込みを確認するまで待機します（1 秒ごとにポーリングします）。終了コードは次のとおりです。

• 0：ポリシーの読み込みに成功しました
• 1：ポリシーの読み込みに失敗しました
• 124：タイムアウト（デフォルトは 60 秒）

Step 6: 更新を確認する

openshell policy list dev

最新のリビジョンのステータスが loaded であることを確認します。failed の場合は、詳細をエラー列で確認してください。

Step 7: 繰り返す

Step 2 に戻ります。必要なアクションがすべて許可され、不要な権限がない状態になるまで、ログの監視とポリシーの調整を続けてください。

ポリシーのリビジョン履歴

すべてのリビジョンを表示して、ポリシーがどのように変化したかを確認します。

openshell policy list dev --page-size 50
openshell policy list dev --output json

特定の過去のリビジョンを取得します。

openshell policy get dev --rev 3 --full

ゲートウェイ全体に適用されるポリシーコマンドでは --global を使います。--yes を指定しない限り、確認が必要です。

openshell policy get --global --full
openshell policy set --global --policy ./global-policy.yaml
openshell policy list --global
openshell policy delete --global

対話的な作業中は --yes を避けてください。グローバルポリシーを設定すると、ゲートウェイ上のすべてのサンドボックスでポリシー制御がロックされます。

エージェントが作成したルール提案をレビューする

--approval-mode manual で作成したサンドボックスでは、すべての提案がレビュー受信トレイに入ります。auto は、証明器による差分が空の有効なポリシー候補のみを自動承認します。指摘事項は引き続きレビューが必要です。CLI は候補の現在のレビュートークンに承認をひも付けます。ライブポリシー、プロバイダー、または認証情報の入力が変更されると、承認してもチャンクは保留状態のままとなり、候補が更新されるため、新たにレビューする必要があります。

openshell rule get dev --status pending
openshell rule approve dev --chunk-id <chunk-id>
openshell rule reject dev --chunk-id <chunk-id> --reason "too broad"
openshell rule history dev

承認する前に、提案されたスコープ、候補のハッシュ、証明器の指摘事項、適用エラーを確認してください。rule approve-all --include-security-flagged は、リスクの高い一括操作として扱ってください。

validation unavailable の場合、ゲートウェイが現在のポリシーと提案されたポリシーの両方を分析できるようになるまで、承認できません。これは、受容済みリスクを示す指摘事項ではありません。

ワークフロー 5：BYOC（Bring Your Own Container）

カスタムコンテナイメージをビルドし、サンドボックスとして実行します。

事前ビルド済みイメージからサンドボックスを作成する

docker build -t my-app:latest .
openshell sandbox create --from my-app:latest --name my-app

--from フラグには、myregistry.com/img:tag などの明示的な OCI イメージ参照を指定します。カタログのエイリアスは展開されません。まず、ローカルゲートウェイと同じコンテナエンジンでローカルの Dockerfile をビルドし、イメージタグを渡してください。

Docker ゲートウェイでは docker build -t my-app:latest を使用してください。Podman ゲートウェイでは podman build -t localhost/my-app:latest を使用し、--from に localhost/my-app:latest を渡してください。リモートゲートウェイでは、ゲートウェイからアクセスできるレジストリにイメージをプッシュしてください。

Docker および Podman ゲートウェイでは、カスタムイメージに非 root の OCI USER を宣言してください。宣言がないイメージは、数値の UID と GID 1000 で実行されます。明示的に指定された各 process.run_as_user または process.run_as_group ポリシーフィールドは、それぞれ独立して優先されます。省略されたフィールドは、イメージの宣言に従います。 明示的な数値フィールドには、1 から 4294967294 までの任意の UID/GID を指定できます。0 は root、4294967295 は無効な ID を示すセンチネル値です。 低い ID を指定すると、一致するアカウント、イメージファイル、マウントされたボリューム、またはデバイスから権限が引き継がれる可能性があることをユーザーに警告してください。

ポートを転送する

# Foreground (blocks)
openshell forward start 8080 my-app

# Background (returns immediately)
openshell forward start 8080 my-app -d

サービスに localhost:8080 でアクセスできるようになりました。 CLI のポート転送では、ユーザーの SSH 設定にある SSH 多重化と自動バックグラウンド化の設定は無視されます。forward list で追跡され、forward stop で管理されるのはバックグラウンド転送のみです。フォアグラウンド転送は、コマンドの終了時に終了します。

サンドボックスを管理または反復的に操作します。

openshell forward list
openshell forward stop 8080 my-app
openshell sandbox delete my-app
openshell sandbox create --from my-app:latest --name my-app --forward 8080

自動化で追跡中の転送メタデータと検証済みプロセス状態が必要な場合は、構造化出力を使用してください。

openshell forward list --output json

各レコードには、workspace、sandbox、bind_address、port、pid、alive が含まれます。alive ブール値は、ワークスペースのスコープ内にあるサンドボックスと、追跡中のプロセス ID を検証します。転送先のソケットは確認しません。

作成とポート転送を 1 つのコマンドで実行します。

openshell sandbox create --from my-app:latest --forward 8080 -- ./start-server.sh

--forward フラグは、コマンドの実行前にバックグラウンドでポート転送を開始します。

ワークフロー 6：エージェント支援型サンドボックスセッション

エージェントがアクティビティを監視し、並行してポリシーを調整する間、人間がサンドボックス内で作業できるようにします。

サンドボックスを作成し、稼働状態を維持します：

openshell sandbox create \
  --name work-session \
  --provider github \
  --provider claude \
  --policy ./dev-policy.yaml

別のシェルで接続するようユーザーに伝えます：

openshell sandbox connect work-session
openshell sandbox connect work-session --editor vscode

拒否されたアクティビティを監視します：

openshell logs work-session --tail --source sandbox

拒否された操作が表示されたら：

1. ネットワークの追加変更には、段階的な更新を優先します： openshell policy update work-session --add-endpoint api.github.com:443:read-only:rest:enforce --binary /usr/bin/gh --wait openshell policy update work-session --rule-name allow_api_github_com_443 --binary /usr/bin/gh --add-allow 'api.github.com:443:POST:/repos/*/issues' --wait

   ルールでは、列挙されているすべてのバイナリが、列挙されているすべてのエンドポイントにアクセスできるようになります。そのため、既存のルールにバイナリまたはエンドポイントを追加する更新では、そのルールのバイナリとエンドポイントのスコープ全体を指定する必要があります。ゲートウェイは、更新で要求されていないバイナリとエンドポイントの組み合わせにアクセスを許可する更新を拒否し、まだ不足しているバイナリをエラーに表示します。あるバイナリにルール内の一部のエンドポイントのみへのアクセスを許可するには、その限定的な許可を独自の --rule-name で指定します。これにより、より広範なルールに統合されず、独自のルールとして維持されます。

   --add-allow と --add-deny には --rule-name と、繰り返し指定する --binary または明示的な --any-binary によるバイナリスコープ全体の指定が必要です。操作では、エンドポイント上のすべてのポートを指定してください。たとえば、api.example.com:443,8443:POST:/admin のように指定します。選択したルール内のエンドポイントを区別するには --endpoint-path を使用します。明示的に空のパスを指定すると、パスセレクターのないエンドポイントが選択されます。ゲートウェイは、永続化する前にスコープの不足や不一致を拒否します。現在のポリシーを確認し、意図した影響範囲を確かめてください。拒否を回避するためだけに、現在のポリシーから指定内容を自動補完しないでください。

2. 広範囲なネットワーク変更、または policy update では表現できない設定変更には、完全な YAML 置換を使用します。これには、既存の大きなスコープを改めて指定しなければならない変更も含まれます。ファイルシステム、Landlock、プロセスの変更には、引き続きサンドボックスの再作成が必要です： openshell policy get work-session --base | sed '1,/^---$/d' > policy.yaml generate-sandbox-policy スキルを使用してポリシーを変更します。 openshell policy set work-session --policy policy.yaml --wait

3. openshell policy list work-session で確認します。

ユーザーが接続を切る必要はありません。ポリシーの更新はホットリロードされ、--wait はサンドボックスがリビジョンを確認するか、タイムアウトになるまで処理をブロックします。セッション終了時にサンドボックスを削除します：

openshell sandbox delete work-session

ワークフロー 7：プロバイダーを接続した推論

推論では、ほかの認証情報が必要なサービスと同じプロバイダー接続ワークフローを使用します。プロバイダーのネイティブエンドポイントを許可するプロファイルをインポートまたは選択し、プロバイダーを作成して、必要とするサンドボックスだけに接続します：

openshell provider profile import -f ./inference-provider.yaml
openshell provider create --name model-provider --type <profile-id> --credential <KEY>
openshell sandbox provider attach work-session model-provider --wait --timeout 30
openshell sandbox exec work-session -- <client-command>

ネイティブベース URL、モデル、リクエスト形式、タイムアウトはアプリケーションが管理します。プロバイダーの接続準備が完了した後に新しいプロセスを起動し、インストールされたプロバイダー環境をそのプロセスに継承させてください。エンドポイント、ポリシー、認証情報のバインド、移行に関する問題には debug-inference スキルを使用します。

通常の静的なプロバイダー更新では、更新を待ってから新しいクライアントプロセスを起動し、新しい参照を取得してください。接続準備が完了すると既存プロセスの環境が更新されたり、古い参照の接続先が変更されたりすると主張しないでください。確認済みの切断では、保持されている参照が無効化され、今後起動するプロセスの環境から削除されます。

ワークフロー 8：ゲートウェイ管理

ゲートウェイを一覧表示、切り替え、検証します。

openshell gateway select
openshell gateway list --output json
openshell gateway select production
openshell gateway info --name production
openshell status

openshell gateway info は、コンピュートドライバー、認証情報ドライバー、ゲートウェイインターセプター、スーパーバイザーミドルウェアの不変の起動時スナップショットを報告します。拡張機能のバージョン不整合を診断する際は、各エントリのプロトコルバージョン、実装バージョン、サポートされる機能、ゲートウェイ要件を使用してください。実装バージョンから、基盤となる Docker、Kubernetes、または認証情報のバックエンドを特定することはできません。

ゲートウェイを登録または削除します。

openshell gateway add http://127.0.0.1:8080 --local --name local
openshell gateway add https://gateway.example.com --name production
openshell gateway remove local

https:// の登録では、エッジ認証がデフォルトで使用されます。保存済みの認証情報を更新または消去するには、gateway login と gateway logout を使用します。OIDC ゲートウェイの場合は、--oidc-issuer と、必要に応じて --oidc-client-id、--oidc-audience、--oidc-scopes を指定します。OIDC の自動更新に失敗すると、保護されたコマンドは RPC を送信する前に停止し、openshell gateway login <name> の実行をユーザーに促します。openshell status では、引き続きゲートウェイへの到達性と認証状態が個別に報告されます。リモート mTLS ゲートウェイでは、--remote USER@HOST または ssh:// エンドポイントを使用します。

一度限りの自動化では、--gateway-endpoint URL を使って、保存済みメタデータを使用せずに直接接続できます。--gateway-insecure は、明示的に信頼された開発用エンドポイントに限って使用してください。

Kubernetes のデプロイを調査します。

helm -n openshell status openshell
kubectl -n openshell get deployment,statefulset,pods,svc
kubectl -n openshell logs deployment/openshell -c openshell-gateway --tail=100
kubectl -n openshell logs statefulset/openshell -c openshell-gateway --tail=100

Docker、Podman、VM を基盤とするゲートウェイでは、ゲートウェイのプロセスまたはコンテナのログと、選択されたランタイムを直接調査してください。

ワークフロー 9：設定管理

サンドボックス単位またはゲートウェイ全体の設定を管理します。

openshell settings get work-session
openshell settings set work-session --key ocsf_json_enabled --value true
openshell settings delete work-session --key ocsf_json_enabled

openshell settings get --global --json
openshell settings set --global --key ocsf_json_enabled --value true

# OCSF schema version downgrade for SIEM compatibility (allowed: "1.1", "1.3")
openshell settings set --global --key ocsf_schema_version --value "1.1"

ocsf_json_enabled を有効にすると、省略形式のログに加えて、スーパーバイザーの標準エラー出力と、ファイルストレージが利用可能な場合はその JSONL ファイルに、コンパクトな OCSF-JSON レコードが追加されます。これらのレコードは、スーパーバイザーのプラットフォームログ（docker logs、podman logs、または kubectl logs）を通じて収集してください。openshell logs では引き続き省略形式のログが表示されます。タイムスタンプの後にある OCSF-JSON マーカーを照合し、残りの部分を JSON として解析してください。配信と保持の制限については、公開されているOCSF JSON エクスポートガイドを参照してください。

グローバル設定の変更時には確認を求められます。レビュー済みの自動化でのみ --yes を使用してください。

policy_validation_failure_mode はゲートウェイの起動時設定であり、 変更可能な openshell settings キーではありません。gateway.toml の [openshell.gateway] に設定し、ゲートウェイを再起動してください。セキュリティを優先するデフォルト設定は fail_closed です。retain_last_valid は、可用性との明示的なトレードオフです。OCSF 設定イベントでは、実行時の検証に失敗した後、以前の世代がアクティブであるかどうかが示されます。

ワークフロー 10：サービスアクセス

ローカルアクセスには forward を、ゲートウェイが管理する HTTP エンドポイントには service を使用します。

# SSH-based same-port forwarding; optional bind address is accepted.
openshell forward start 127.0.0.1:8080 my-app -d

# gRPC relay to a loopback TCP service, with an optional dynamic local port.
openshell forward service my-app --target-port 8000 --local 127.0.0.1:0

# Create a sandbox with its unnamed HTTP or WebSocket service exposed.
openshell sandbox create \
  --name my-app \
  --from my-app:latest \
  --expose 8080 \
  --expose-authorization-mode bearer-passthrough \
  --detach \
  -- ./start-server.sh

# Expose and manage an HTTP service through the gateway.
openshell service expose my-app 8080 web \
  --authorization-mode bearer-passthrough
openshell service list my-app
openshell service list my-app --output json
openshell service get my-app web
openshell service delete my-app web

ワークスペース全体を対象としたプラットフォーム管理者向けのビューには、openshell service list --all-workspaces を使用します。サンドボックス名と --all-workspaces は同時に指定できません。

sandbox create --expose PORT は、作成リクエストで名前のないエンドポイントを登録し、サンドボックスを実行中の状態に保ちます。自動化では --output json を追加します。結果には service_urls マップが含まれ、空のキーが名前のないエンドポイントを示します。作成後に名前付きエンドポイントを追加または更新するには、openshell service expose を使用します。

公開されたサービスでは、デフォルトで Authorization が削除されます。サンドボックス内のアプリケーションが独自のクライアントを認証する場合に限り、bearer-passthrough を選択してください。このモードでは、Authorization ヘッダーがないか、空ではない Bearer 認証情報が 1 つだけ含まれている場合に限り受け付け、その値を変更せずに転送します。アプリケーションに接続する前に、重複した認証情報、形式が正しくない認証情報、または Bearer 以外の認証情報は拒否されます。トークンの検証は引き続きアプリケーションの責任であり、未加工のトークンがサンドボックスのプロセスに渡されるため、決してログに記録しないでください。サービスルートはコントロールプレーンの RPC 認可を経由しませんが、クライアント証明書が必要な場合を含め、ゲートウェイの既存のリスナー、ドメインルーティング、TLS 設定は引き続き適用されます。セキュリティ要件の全容については、公開されているサンドボックスサービスのドキュメントを参照してください。

ユーザーが LAN から見えるローカルアクセスを明示的に必要としている場合を除き、ループバックバインドを優先してください。

---

--help を使った自己学習

このスキルで説明されていないコマンドやオプションに遭遇した場合は、次の手順に従います。

1. まず全体を確認する：openshell --help で、すべてのコマンドグループを確認します。
2. 範囲を絞る：openshell <group> --help でサブコマンドを確認します（例：openshell sandbox --help）。
3. 詳細を確認する：openshell <group> <cmd> --help でフラグと使い方を確認します（例：openshell sandbox create --help）。

CLI のヘルプは常に正式な情報源です。ヘルプの出力がこのスキルの内容と矛盾する場合は、ヘルプの出力に従ってください。このスキルの作成後に CLI が更新されている可能性があります。

例：見慣れないコマンドを調べる

$ openshell sandbox --help
# Shows: create, get, list, stop, start, delete, exec, connect, upload, download, ssh-config, provider, template

$ openshell sandbox upload --help
# Shows: positional arguments (name, path, dest), usage examples

---

関連スキル

スキル	使用する場面
generate-sandbox-policy	ポリシー YAML の内容（ネットワークルール、L7 インスペクション、アクセスプリセット、エンドポイント設定、ネットワークミドルウェア）を作成または変更するとき
debug-openshell-cluster	ゲートウェイのデプロイ、ランタイム、またはヘルスの障害を診断するとき
debug-inference	接続されたプロバイダーの推論、ネイティブエンドポイント、ホスト連携モデル、および廃止されたマネージドエンドポイントからの移行を診断するとき