管理サーバー (Admin Server)

管理サーバー（Admin Server）は組織内のプライベートネットワーク内で動作し、Griptape Nodes アプリケーションインスタンスに代わって Griptape Cloud と通信する単一のホストとして機能します。各インスタンスは cloud.griptape.ai に直接アクセスする代わりに管理サーバーを参照し、管理サーバーが各リクエストをアップストリーム（クラウド）へ転送します。これにより、個々の端末をパブリックインターネットから隔離したまま、ライセンス認証、セッション実行、および Griptape Cloud の各機能を利用できるようになります。

導入のメリット (Why use it)

Griptape Nodes をオンプレミスで運用するスタジオ環境では、通常、個々のクライアント端末がそれぞれパブリックインターネットに直接アクセスすることは望まれません。管理サーバーを導入することで、その外部接続を一元管理できます：

端末のインターネット隔離 (Lock instances down): アプリケーションインスタンスは管理サーバーとのみ通信するため、個別のインターネット送信（エグレス）を完全に遮断できます。
外部送信ポイントの集約 (One egress point): 端末ごとに外部アクセスを許可する代わりに、ファイアウォール上で 1 台のホストのみを許可すれば済みます — 管理すべきルールが 1 つになり、アウトバウンドトラフィックの監査も容易になります。
設定の一元化 (Central configuration): Griptape Cloud の接続先や、ネットワーク外への送信を許可するクラウドパス（API ルート）を、端末ごとではなく一箇所で集中設定できます。

個々のアプリケーション端末がすでに cloud.griptape.ai に直接アクセス可能であり、それが組織のポリシー上許容される場合は、管理サーバーを導入する必要はありません。

管理サーバーの配置場所や通信フローの図解については、アーキテクチャ: オンプレミス構成を参照してください。

管理サーバーの入手方法 (Getting the Admin Server)

管理サーバーはエンタープライズ顧客向けに提供されます。Foundry のデモ申し込み窓口に連絡して入手してください。

主な機能 (Capabilities)

Cloud リクエストの転送 (Forwards Cloud requests): 各アプリケーションからの Griptape Cloud 向けリクエストを設定されたアップストリーム（デフォルトは https://cloud.griptape.ai）へ転送し、呼び出し元の Authorization ヘッダーをそのまま保持します。これにより、ライセンス認証やセッション管理が正常に継続されます。認証・認可の権威（Authority）は引き続き Griptape Cloud が担います。
起動時の接続検証 (Validates at startup): 起動時に管理者の Griptape Cloud API キーを一度検証するため、設定不備がある場合は後から障害が起きるのではなく、起動時に即座に検知できます。
外部送信フィルタリング (Egress filtering): ネットワーク外への送信を許可する Cloud パスを厳密に制限できます（forwarding を参照）。
ヘルスチェックエンドポイント (Health endpoint): 生死監視（Liveness / Readiness probe）用に {"status":"ok"} を返すローカルの GET /health エンドポイントを備えています。
構造化ロギング (Structured logging): 監査目的のために、各リクエストの完了時に 1 回（HTTP メソッド、パス、ステータス、レイテンシ、クライアント IP、送信バイト数）を JSON またはプレーンテキスト形式でログ出力します。

設定 (Configuration)

管理サーバーは config.yaml ファイルから設定を読み込みます。設定は以下の優先順位で解決され、後から読み込まれたソースが前のものを上書きします：

組み込みのデフォルト値
config.yaml ファイル（デフォルトパス。起動時に別のパスを指定可能）
環境変数（最優先）

対象バージョンについて

このページは管理サーバーバージョン 0.3.0 以降を前提に記述されています。./server -version を実行してバージョンを確認してください。それ以前のバージョンでは、read_timeout および write_timeout のデフォルトが 30s に設定されており、ストリーミング応答が途中で切断されてしまいます。設定すべき値については後述の警告を参照してください。

デフォルト値を含む完全な config.yaml の例：

server:
  host: "0.0.0.0"
  port: 8080
  read_header_timeout: "10s"
  write_stall_timeout: "60s"
  idle_timeout: "120s"
  shutdown_timeout: "10s"

upstream:
  base_url: "https://cloud.griptape.ai"
  timeout: "120s"
  # Griptape Cloud API キーを保持する環境変数の名前。
  # キー自体の文字列はここには記述せず、変数名のみを指定します。
  api_key_env: "GT_CLOUD_API_KEY"

logging:
  level: "info"   # debug | info | warn | error
  format: "json"  # json | text

forwarding:
  mode: "allow_all"  # allow_all | allow | deny
  rules: []

server

設定キー	デフォルト値	説明
`host`	`0.0.0.0`	サーバーがリッスンするアドレス。
`port`	`8080`	サーバーがリッスンするポート番号。
`read_header_timeout`	`10s`	リクエストヘッダーが到着するまでの制限時間（期間文字列、例: `10s`）。
`write_stall_timeout`	`60s`	クライアントへの単一の書き込みがブロック可能な最大時間。接続が切断されるまでの時間です。書き込みごとに再設定されるため、全体の応答時間を制限するものではありません。`0` で無効化。
`idle_timeout`	`120s`	リクエスト間でアイドル状態の Keep-Alive 接続を開いたまま維持する時間。
`shutdown_timeout`	`10s`	グレースフルシャットダウン時に処理中のリクエストが完了するのを待機する制限時間。
`read_timeout`	`0`（無効）	非推奨。リクエスト全体の読み取り制限時間。アップロードの最大時間を制限してしまいます。代わりに `read_header_timeout` を使用してください。
`write_timeout`	`0`（無効）	非推奨。レスポンス全体の書き込み制限時間。`0` より大きい値を設定すると、ストリーミング応答が途中で強制切断されます。代わりに `write_stall_timeout` を使用してください。

write_timeout はストリーミング応答を切断します

以前のバージョンのドキュメントや設定サンプルには、read_timeout: "30s" および write_timeout: "30s" と記載されていました。config.yaml にこれらの行が含まれている場合は、"0" に設定してください:

server:
  read_timeout: "0"
  write_timeout: "0"

"0" を指定する設定は、すべてのバージョンにおいて安全で適切です。行自体の削除は、デフォルトがすでに 0 に変更された 0.3.0 以降でのみ有効です — それより前のビルドで行を削除すると、そのビルド固有の 30s デフォルトにフォールバックしてしまい、応答の途切れが再発します。すべての環境が 0.3.0 以降に更新された段階で、これらの行を完全に削除できます。

write_timeout は、リクエストが到着した瞬間から計測される応答全体の制限時間であり、アイドルタイムアウトではありません。エージェントの返答は 1 トークンずつストリーミングされ、30 秒以上かかるのが普通であるため、この制限時間を超えるとサーバーが応答を途中で切断してしまいます。Griptape Nodes の UI 上ではチャットの返答が文章の途中で突然停止し、アプリケーションログには以下のように記録されます：

httpx.RemoteProtocolError: peer closed connection without sending complete message body

write_stall_timeout はこれに代わる設定です：単一の書き込みがブロックできる時間を制限するため、応答を受け取らなくなった停止クライアントを適切に切断しつつ、正常なストリームは必要なだけ継続させることができます。

この挙動を検証するためにファイルを直接編集する必要はありません — 環境変数は config.yaml よりも優先されます：

export SERVER_WRITE_TIMEOUT=0
# その後、管理サーバーを再起動

upstream

設定キー	デフォルト値	説明
`base_url`	`https://cloud.griptape.ai`	サーバーが転送する Griptape Cloud のルート URL。
`timeout`	`120s`	Griptape Cloud が応答を開始するまでの待機時間。全体の応答時間を制限するものではないため、ストリーミング応答には影響しません。ストリーミングされないリクエストは回答全体が生成されるまで何も送信されないため、このデフォルトは長めに設定されています — 時間のかかる生成処理で `502 Bad Gateway` が発生する場合は、この値を増やしてください。
`api_key_env`	`GT_CLOUD_API_KEY`	Griptape Cloud API キーを保持する環境変数の名前。

管理サーバーには Griptape Cloud API キーが必要です。サーバーは起動時にこれを検証し、オペレーターが Griptape 組織を所有していることを確認します。このキーはリクエストのパス上では使用されません — クライアントアプリケーションは独自の Authorization ヘッダーを送信し、管理サーバーはそれをそのまま転送します。

キーの値自体は config.yaml に保存してはなりません。代わりに api_key_env でキーを読み取る環境変数名（デフォルトは GT_CLOUD_API_KEY）を指定し、環境変数側でキーを設定します：

export GT_CLOUD_API_KEY="gt-..."

別の変数名を使用したい場合は、api_key_env を設定した上でその名前でキーをエクスポートしてください。

API キーをバージョン管理にコミットしないでください

API キーは config.yaml ではなく、常に環境変数として管理してください。設定ファイルにはキーを読み取る環境変数の名前のみを指定するため、リポジトリにコミットされるファイル内にキー文字列が含まれるリスクを排除できます。

logging

設定キー	デフォルト値	説明
`level`	`info`	ログの詳細度: `debug`、`info`、`warn`、`error`。
`format`	`json`	ログ出力形式: `json` または `text`。

管理サーバーは標準出力（stdout）と標準エラー出力（stderr）にログを出力します — ログファイルは作成されません。ファイルが必要な場合は、起動時にリダイレクトするか（./server -config config.yaml > admin-server.log 2>&1）、コンテナランタイムやサービスマネージャーにストリームを収集させてください。ログ収集基盤を通さずに目で直接確認する場合は、format: "text" を設定してください。

リクエストが途中で終了した原因を診断する際に役立つ 3 つの重要なログ：

ログ行	意味
`starting server`	`config.yaml` および環境変数のオーバーライドが解決された、実際に有効なすべてのタイムアウト値を一覧表示します。最初にこれを確認してください。
`response stream aborted before completion`	レスポンスが完了前に中断されました。`bytes_out`（どこまで送信されたか）と `request_id` が含まれます。通常の原因はユーザーが途中でタブを閉じたことですが、書き込み制限時間の超過が原因である場合もあります。
`panic recovered`	管理サーバー自体の不具合（バグ）。呼び出し元には `500` が返されます。開発元への報告対象です。

forwarding

forwarding ブロックは、管理サーバーを通過して外部に送信できる Cloud パスを制御します。これはアップストリーム側のアクセス制御の上に重ねて適用される、社内ネットワーク用の送信（エグレス）制御機能です。

設定キー	デフォルト値	説明
`mode`	`allow_all`	`allow_all`、`allow`、または `deny`（下記参照）。
`rules`	(空)	許可または拒否するパス。各ルールは絶対パスで指定し、末尾に `/*` を付けると前方一致プレフィックスマッチになります。

3 つのモード：

allow_all（デフォルト） — すべてのパスの転送を許可します。rules は無視されます。
deny — 一致するパス以外のすべてを転送します。特定のパスのみを例外的にブロックしたい場合に最適です。
allow — 一致するパスのみを転送します。公開面を最小限に絞り込む厳格なセキュリティ態勢（ホワイトリスト方式）です。

各ルールは絶対パスです。末尾に /* を付けると前方一致（/api/proxy/* は /api/proxy およびその配下のすべてに一致）となり、付けない場合は完全一致となります。許可されていないパスへのリクエストは、外部へ転送されることなくローカルで 403 {"error":"path not permitted"} として拒否されます。

例えば、他のすべての通信を転送しつつ、Griptape Cloud のモデルプロキシへの通信のみを社内に留める場合：

forwarding:
  mode: "deny"
  rules:
    - "/api/proxy/*"

最も厳格な制限を課す場合は、allow モードを使用し、アプリケーションが実行時に必要とするルートのみをリストアップします。それ以外の通信は一切外部へ出ません。以下はアプリケーションの動作に必須のルートです — allow モードにおいてこれらのいずれかが欠落している場合、管理サーバーは起動を拒否します：

forwarding:
  mode: "allow"
  rules:
    - "/api/sessions/*"     # セッションの割り当てとライフサイクル（/api/sessions/{id} を含む）
    - "/api/session-renew"  # セッションの維持
    - "/api/session-release" # セッションの終了
    - "/api/users"          # 起動時およびハートビートごとに取得
    - "/api/organizations"  # 起動時およびハートビートごとに取得

これらは製品の動作に最低限必要なセットです。許可したい Cloud 機能（例えばモデルプロキシ用の /api/proxy/* など）に応じて、必要なルールを追加してください。

認証ではなく外部送信（エグレス）の制御です

転送ルールは「社内ネットワークから外部へ出てよいパス」を決定するものであり、ユーザーのアクセス権限を認証するものではありません — 誰が何を呼び出せるかの認可権威は Griptape Cloud にあります。アプリケーションの実行に不可欠なコアルート（セッションライフサイクル、ユーザー、組織関連）は決してブロックできません。設定によってこれらがブロックされる場合、管理サーバーは起動を拒否して該当するルート名を指摘します。これにより、誤った設定によって製品が停止する事態を防ぎながら安全にエグレスを絞り込むことができます。

環境変数によるオーバーライド

すべての設定項目は環境変数でオーバーライドでき、config.yaml よりも常に優先されます：

環境変数	デフォルト値	説明
`GT_CLOUD_API_KEY`	(必須)	Griptape Cloud API キー（または `upstream.api_key_env` で指定された変数）。
`SERVER_HOST`	`0.0.0.0`	リッスンアドレス。
`SERVER_PORT`	`8080`	リッスンポート番号。
`SERVER_READ_HEADER_TIMEOUT`	`10s`	リクエストヘッダー到着期限。
`SERVER_WRITE_STALL_TIMEOUT`	`60s`	読み取りを停止したクライアントに対する書き込み制限時間。
`SERVER_IDLE_TIMEOUT`	`120s`	アイドル Keep-Alive 接続の維持期限。
`SERVER_SHUTDOWN_TIMEOUT`	`10s`	グレースフルシャットダウン待機期限。
`SERVER_READ_TIMEOUT`	`0`（無効）	非推奨。リクエスト全体の読み取り制限。アップロード時間を制限。
`SERVER_WRITE_TIMEOUT`	`0`（無効）	非推奨。レスポンス全体の書き込み制限。ストリーミングを切断。
`UPSTREAM_BASE_URL`	`https://cloud.griptape.ai`	アップストリームの Griptape Cloud ルート URL。
`UPSTREAM_TIMEOUT`	`120s`	アップストリームの応答開始待機時間。
`UPSTREAM_API_KEY_ENV`	`GT_CLOUD_API_KEY`	API キーを保持する環境変数名。
`LOG_LEVEL`	`info`	ログの詳細度。
`LOG_FORMAT`	`json`	ログ出力形式。
`FORWARDING_MODE`	`allow_all`	`allow_all`、`allow`、または `deny`。
`FORWARDING_RULES`	(空)	許可または拒否するパスのカンマ区切りリスト。

期間（duration）の値には必ず単位を指定してください（30s、2m など）。0 はタイムアウトの無効化を意味します。単位のない数値（SERVER_READ_TIMEOUT=30 など）を指定すると、意図しない値で暗黙に動作するのを防ぐため、管理サーバーは起動を拒否します。

実行手順

環境変数に Griptape Cloud API キーを設定します：
```
export GT_CLOUD_API_KEY="gt-..."
```
必要に応じて config.yaml を用意し（設定を参照）、管理サーバーを起動します。デフォルトでは 0.0.0.0:8080 でリッスンし、https://cloud.griptape.ai に転送します。
Griptape Nodes アプリケーションインスタンスの接続先エンドポイントを、cloud.griptape.ai ではなく管理サーバーのアドレスに変更します。

API キーが見つからない、無効である、またはアップストリームに到達できない場合、管理サーバーは理由をログに出力して終了するため、設定上の問題はすべて起動時に明確になります。

トラブルシューティング

チャットの返答が文章の途中で途切れる、またはアプリケーションログに peer closed connection without sending complete message body が記録される。ストリーミング応答が途中で強制切断されています。ほとんどの場合、config.yaml に write_timeout が設定されていることが原因です（前述の警告を参照）。これを "0" に設定するか（または環境変数 export SERVER_WRITE_TIMEOUT=0 を設定）、サーバーを再起動してください。管理サーバー自身のログでこれを確認できます。起動時の starting server 行で使用中のすべてのタイムアウトが報告されるため、まずそこの write_timeout を確認してください。response stream aborted before completion の警告ログには、サーバーが応答を終了した事実と送信できたバイト数が記録されます。もし write_timeout=0s なのに依然として途切れる場合は、管理サーバーの前段にあるロードバランサー、Ingress コントローラー、TLS 終端プロキシのタイムアウト設定を確認してください。
ストリーミングされない長い生成処理で 502 Bad Gateway が発生する。 upstream.timeout は Griptape Cloud が応答を開始するまでの時間を制限しています。ストリーミングされない生成処理では、結果全体が完成するまで何もデータが送信されません。この待機時間設定の値を増やしてください。
大きなファイルのアップロードが途中で失敗する。 read_timeout はリクエストボディ全体が届くまでの時間を制限しているため、実質的にアップロードサイズを制限します。0.3.0 以降ではデフォルトで無効化されていますが、config.yaml で設定されている場合は "0" に変更してください。
サーバーが起動しない。 GT_CLOUD_API_KEY が正しく設定されているか確認してください。管理サーバーは起動時にこれを検証し、認証に失敗すると起動を停止します。また、環境変数名を指摘する起動エラー（invalid SERVER_WRITE_TIMEOUT: "30" is not a duration など）が出ている場合は、単位（30s など）が抜けていないか確認してください。
すべてのリクエストで 502 が返される。 管理サーバーがアップストリームに到達できていません。upstream.base_url に対する外部ネットワーク疎通、DNS 解決、社内プロキシによる TLS インスペクションの設定を確認してください。
403 {"error":"path not permitted"} が返される。 forwarding ルールによってそのパスがブロックされています。そのパスの通信が必要な場合は、forwarding.mode や forwarding.rules を見直してください。