環境変数
すべて OSUI_ 接頭辞で、.env からも読み込めます。認証に関わる項目の背景は セキュリティ を参照してください。
| 変数 | 既定値 | 説明 |
|---|---|---|
OSUI_AUTH_TOKEN | (任意) | 設定すると全 API およびコンソールが保護されます。公開 bind 時は必須。 |
OSUI_HOST / OSUI_PORT | 127.0.0.1 / 8080 | バインド先。loopback 以外は token が必須。 |
OSUI_GATEWAY_ENDPOINT | (SDK 自動検出) | 明示的に gateway を指定する場合に使用。空なら active cluster を読みます。 |
OSUI_WORKSPACE | default | 操作対象ワークスペース。 |
OSUI_DEMO | false | true で demo backend を強制。Vercel / Colab 向け。 |
OSUI_ALLOW_QUERY_TOKEN | false | ?token= での認証を許可するか。URL はログ・履歴・Referer に残るため既定で無効。 |
OSUI_REQUIRE_GATEWAY | false | true で demo フォールバックを禁止し、接続できなければ起動を失敗させます。 |
OSUI_SSE_ENABLED | true | SSE エンドポイントを公開するか。Cloudflare Quick Tunnel では false を推奨。 |
OSUI_GATEWAY_CA_CERT / OSUI_GATEWAY_CERT / OSUI_GATEWAY_KEY | (任意) | CA 検証と mTLS クライアント証明書。CERT と KEY は同時指定が必須。 |
OSUI_OIDC_ISSUER / OSUI_OIDC_CLIENT_ID / OSUI_OIDC_CLIENT_SECRET / OSUI_OIDC_AUDIENCE | (任意) | OIDC クライアント認証。リモート gateway へ接続する際に使用します。 |
OSUI_EXEC_DEFAULT_TIMEOUT / OSUI_EXEC_MAX_TIMEOUT | 60 / 1800 | コマンド実行の既定/上限タイムアウト(秒)。 |
OSUI_PAGE_SIZE | 100 | 一覧取得時のページサイズ。 |
OSUI_CORS_ORIGINS | [] | CORS 許可オリジンの JSON 配列。 |
OSUI_GATEWAY_CLUSTER | (任意) | 接続先 cluster 名。SDK 側の上書き。 |
ガイドの訂正点(実 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のようなコマンドは存在しません。
エラーと対処
主要なエラーが返る状況と、UI 上での挙動・対処法です。トースト通知など UI 上のメッセージはコンソールにも出力されます。
| 状態 | 発生する場面 | UI 上の挙動 | 対処 |
|---|---|---|---|
401 | トークン未設定・不一致(Authorization / Sec-WebSocket-Protocol / ?token=) | アクセストークン入力パネルを表示 | OSUI_AUTH_TOKEN と同じ値を入力 |
404 | 存在しないサンドボックス、または SSE 無効化時の /exec/stream | コンソールに [error] not found を出力 | 一覧から正しい名前を選択 |
422 | 未実装フィールド(env 等)や不正なペイロード | 422 の詳細をコンソールに出力 | サポート対象のフィールドのみ送信 |
503 | OSUI_REQUIRE_GATEWAY=true で gateway に到達できない | 起動に失敗(fail-fast) | gateway の起動・endpoint を確認 |
4401(WS) | WebSocket ハンドシェイク時の token 失敗 | 接続切断・再実行可能 | トークンを確認して再接続 |
起動経路の失敗(README / LP の手順どおりでない条件)の詳細は USAGE.md のトラブルシューティングも参照してください。
リポジトリ構成
| パス | 内容 |
|---|---|
src/openshell_ui/core/ | 設定、モード判定、backend factory、OpenShell / demo adapter |
src/openshell_ui/api/ | auth、health/config、CRUD、exec(REST / WebSocket / SSE) |
src/openshell_ui/ui/ | 同梱のダッシュボード(HTML / CSS / JS) |
deploy/ | Cloudflare config、Dockerfile、Colab notebook |
policy/ | OpenShell policy(version 1) |
site/ | この LP(GitHub Pages) |
.github/ | CI / Pages ワークフロー、Issue・PR テンプレート |
CONTRIBUTING.md / CHANGELOG.md | 開発参加ガイド / 変更履歴 |