AI の機能解説FEATURE GUIDEforva AI

Claude CodeAnthropic の機能

FEATURE

Self-hosted runner(セルフホストランナー)

Self-hosted runner(セルフホストランナー)は、claude self-hosted-runner によって自前のマシンやコンテナを、Claude Code の Web・モバイル・デスクトップのセッションが実行される場所にする機能です。

提供中公式発表と照合済み
初出未調査
ページ更新
提供状態提供中
公式の記載で確認できた環境ターミナル、デスクトップアプリ、Web ブラウザ、スマホアプリ
提供を確認できたプランEnterprise、Team
目次 CONTENTS
  1. できること
  2. 機能解説
  3. 利用シーン
  4. ChatGPT・OpenAI の対応する機能
  5. これまでの変更
  6. 関連する機能
  7. 出典
CAN DO

できること

POINT 01

自前の環境でセッション実行

claude self-hosted-runner を使うと、自前のマシンやコンテナを Claude Code の Web・モバイル・デスクトップのセッションの実行場所にできます。

POINT 02

停止時の挙動を制御

--defer-shutdown-max-min を指定すると、SIGTERM を受けた後も指定した分数まで接続中のセッションを処理し続け、残ったセッションを一時停止してから終了します。オーケストレーターでは --shutdown-drain-sec で、処理中のポーリングと spawn フックに完了までの猶予を与えられます。

POINT 03

社内ネットワークへの適合

接続ごとに新しい Proxy-Authorization ヘッダーを要求する egress プロキシ向けに --proxy-authorization-command / --proxy-authorization-file を使えます。--client-label でランナーが登録するラベル(既定はホスト名)も上書きできます。

GUIDE

機能解説

概要

Team と Enterprise プランで提供されます。自社で管理する計算環境の上で Claude Code のセッションを動かしたい場面に関わる機能です。

Self-hosted runner は、claude self-hosted-runner コマンドで自前のマシンやコンテナを Claude Code セッションの実行場所にします。Claude Code の Web・モバイル・デスクトップから開始したセッションが、このランナー上で動きます。

ランナーのセッションでは、サーバー提供の Claude Code フックがサポートされており、managed-environment(管理された環境)と同じ挙動です。起動やセッションの失敗には構造化された失敗カテゴリが付き、フックエラー、ランナーのクラッシュ、設定エラーを区別できます。

クラウドとセルフホストランナーの Claude Code Remote セッションでは、組織が許可する範囲で fast mode を使えます。ホストの fast-mode 設定、またはセッション内で入力した /fast が適用されます。

導入・運用時に確認したい点

  • Windows での起動: Windows では既定のチェックアウト先ディレクトリが無く、起動時に --base-dir の明示的な指定が必要です。
  • システムプロンプトの渡し方: ランナーはシステムプロンプトをコマンドライン引数ではなくプライベートファイルとして Claude Code に渡します。--system-prompt や --append-system-prompt を追加するラッパーやコマンドフックは、--system-prompt-file または --append-system-prompt-file への切り替えが必要です。
  • チェックアウトフックの時間制限: チェックアウトフックは既定で 30 分後に停止され、セッションのセットアップは失敗します。より長い時間が必要な場合は --checkout-hook-timeout-min を引き上げるか、0 にして無効化します。
  • セッションごとのデータの削除: --remove-session-state(既定はオフ)を指定すると、セッション終了時に <base-dir>/_sessions/ 配下のセッションごとのディレクトリを削除します。
  • 長時間のセッションの扱い: --kill-session-after-min は、ユーザーの応答待ちだけのセッションを強制終了せず、一時停止状態で解放します。次のメッセージで再開できます。
  • **ネストした claude -p の扱い**: 環境変数 CLAUDE_CODE_DISABLE_NESTED_SESSION_ID を 1 にすると、セッション内で実行した claude -p が以前のバージョンと同じく、そのセッションの ID とトランスクリプトを使います。

提供状況の注意

claude self-hosted-runner による自前のマシンやコンテナでのセッション実行は、Team と Enterprise プランで提供されます。提供地域については、公式のリリースノートには記載がありません。

USE CASES

利用シーン

CASE 01

自社で管理するマシンやコンテナの上で、Claude Code の Web・モバイル・デスクトップのセッションを動かす運用に向いています。

CASE 02

接続ごとに新しい Proxy-Authorization ヘッダーを要求する egress プロキシを経由するネットワークでの運用に使えます。

CASE 03

SIGTERM でランナーを停止させる運用で、接続中のセッションを処理しながら終了させたい場面に使えます。

CASE 04

複数のランナーを、--client-label で付けたラベルで見分けたい場面に使えます。

COMPARISON

ChatGPT・OpenAI の対応する機能

比較の単位となる業務: 自前のマシンやコンテナでのリモートコーディングエージェントセッションの実行

Codex Mobile は、ChatGPT モバイルアプリを、Codex アプリを実行している Mac に接続して Codex を使う仕組みです。Codex は接続されたホストから実行されるため、そのホストのプロジェクト、ファイル、認証情報、プラグイン、スキル、設定をスマホから利用できます。Self-hosted runner は、自前のマシンやコンテナを Claude Code の Web・モバイル・デスクトップのセッションの実行場所にするもので、実行場所としてマシンやコンテナを対象にしています。

失敗の扱いについては、Codex app server ではより多くの app-server の失敗を再起動が必要なものとして分類しています。Self-hosted runner では、起動・セッションの失敗に構造化された失敗カテゴリを付け、フックエラー、ランナーのクラッシュ、設定エラーを区別します。

TIMELINE

これまでの変更

  1. CLAUDE_CODE_DISABLE_NESTED_SESSION_ID が追加されました。同日、501・529 以外の 5xx エラーの後、次のポーリングで失敗した接続を再利用せず新しい接続を開く動作に改善されました。

  2. --hold-idle-file と --max-hold-min が追加され、セッションが残したプロセスをホストが報告している間、アイドル状態のセッションを保持できます。

  3. チェックアウトフックが既定で 30 分後に停止される動作に変わりました。

  4. オーケストレーターに --shutdown-drain-sec が追加されました。

  5. Anthropic 管理の git を使うセッション向けに、GitHub CLI が入っていない macOS・Linux マシンで使える組み込みの gh api(REST のみ)が追加されました。

  6. システムプロンプトをプライベートファイルとして渡す方式に変わり、大きなプロンプトで起動が失敗しなくなりました。

  7. Claude Code Remote セッションでの fast mode と、--drain-marker-file が追加されました。--drain-marker-file は、SIGTERM のドレイン時に指定ファイルが存在すれば、終了をホストドレインとしてサーバーに報告します(テレメトリのみ)。

  8. --remove-session-state が追加されました。

  9. --kill-session-after-min が、ユーザー待ちだけのセッションを一時停止状態で解放する動作に変わりました。

  10. --client-label(または SELF_HOSTED_RUNNER_CLIENT_LABEL)が追加されました。

  11. --defer-shutdown-max-min と、--proxy-authorization-command / --proxy-authorization-file が追加されました。

  12. セッション開始時間が改善されました。セッションブランチを作業ツリーの書き換え無しで作成し、2 回のサーバー往復がエージェントの起動を待たせなくなりました。同日、サーバー提供の Claude Code フックへの対応と、Windows での --base-dir の必須化も行われました。

  13. self-hosted environments が追加され、claude self-hosted-runner で自前のマシンやコンテナを Claude Code の Web・モバイル・デスクトップのセッションの実行場所にできます(Team と Enterprise プラン)。

  14. ランナーの起動・セッション失敗に構造化された失敗カテゴリが追加され、フックエラー、ランナーのクラッシュ、設定エラーを区別できます。

SOURCES

出典

出典 16 件を表示