本番環境へのセルフホスト環境のデプロイ

​

デプロイを強化する

• エフェメラルなセッションごとのコンテナ：各ランナープロセスを、プロセスが終了するときに破棄される新しいコンテナまたは VM で実行します。--capacity 1 とデフォルトの --drain-grace-sec 0 を使用して、各コンテナが正確に 1 つのセッションを処理するようにします。容量が高い場合、またはドレイングレースが正の場合、1 つのコンテナが同じロックされたオーナーからの複数のセッションを処理します。ランナーのライフサイクルを参照してください。ランナーの再起動間でファイルシステムを再利用しないでください。ただし、意図的なプリウォーミングされたチェックアウトセットアップは除きます。また、オーナー間では再利用しないでください。
  • ランナーがセッションを停止するとき、シェルコマンドの終了後も実行を続けているプロセス（デーモン化したサービスなど）にはシグナルを送信しません。コンテナまたは VM を破棄すると、そのプロセスは終了します。
• イメージに広範な認証情報を含めない：長期的な SSH キー、クラウドプロバイダーの認証情報、またはセッションが必要とする以上の権限を付与するパーソナルアクセストークンを含めないでください。セッション中に使用される認証情報（プッシュトークンや API トークン）は、ラッパースクリプトからセッションごとにミントしてください。初期クローンはラッパーが実行される前に発生するため、checkout ライフサイクルフックで処理するか、セッションのすべてのリポジトリが github.com 上にある場合は --use-anthropic-git-proxy で処理してください。どちらについても、git を設定するを参照してください。
• ホストの GitHub 認証情報をセッションから遠ざける：Claude は、セッションが読み取れる任意の GitHub 認証情報を、その認証情報が付与するアクセス権の範囲で使用できます。ランナーホスト自身の広範なスコープを持つ GitHub 認証情報は、セッションが読み取れる場所に置かないでください。このような認証情報には、パーソナルアクセストークン、gh auth login がアカウント用に保存するトークン、ランナーの環境内の GH_TOKEN などがあります。
  • Anthropic 管理の git を使用する場合：このような認証情報があると、Claude は Anthropic 管理の git を経由せずに GitHub に直接アクセスします。
  • Anthropic 管理の git を使用しない場合：イメージに git 設定を含めるで説明しているとおりに厳密にスコープを限定すれば、クローン用の認証情報をイメージに残しておくことができます。
• 環境シークレットをセッション実行ホストに置かない：環境シークレットはランナーを登録し、環境でキューに入っているセッションを取得できます。固定フリートでは、シークレットはすべてのランナーホストに存在し、どのセッションのコードもシークレットファイルを読み取ることができます。オンデマンドランナーを優先してください。この場合、シークレットはユーザーコードを一切実行しないオーケストレーターホストに留まり、各ランナーは正確に 1 つのランナーを登録する単一使用の作業指示を受け取ります。固定フリートでは、環境シークレットファイルをすべてのセッションで読み取り可能として扱い、セッション侵害が疑われる場合はその後にシークレットをローテーションしてください。
• デフォルト拒否ネットワーク出力：すべての環境でランナーとセッションコンテナのアウトバウンドトラフィックをネットワーク境界で制限してください。デフォルト拒否出力では、許可する内容と理由について説明しています。
• 最小権限ホスト IAM：ランナーホストに接続されたコンピュート ID（インスタンスプロファイルやノードサービスアカウントなど）は、ランナー自体が必要とするもののみを付与する必要があります。セッションは、ホストの ID を継承するのではなく、ラッパースクリプトを通じて独自の認証情報を取得する必要があります。
• セッションからクラウドメタデータエンドポイントをブロックする：セッションにホスト ID を使わせないようにするには、クラウドメタデータエンドポイントへのアクセスをブロックする必要があります。サブネットレベルの出力ポリシーはリンクローカルメタデータトラフィックをインターセプトしないため、コンテナ自体でブロックしてください：
  • ホップリミットが 1 の IMDSv2
  • メタデータ隠蔽を備えた GKE Workload Identity
  • セッションコンテナのネットワーク名前空間で 169.254.169.254 の明示的な拒否
  ブロックはラッパースクリプトとライフサイクルフックにも適用されます。これらはコンテナを共有するためです。トークン交換をセッション JWTで認証し、許可リストに登録された出力を通じて独自のトークンサービスに対して行うか、Amazon EKS の IAM Roles for Service Accounts（IRSA）などのファイルベースの Web ID を使用してください。
• ランナーごとのファイルシステム分離：各ランナープロセスは、ホスト上の他のプロセスが読み取りまたは書き込みできない独自の作業ディレクトリを取得します。--hooks-dir、ラッパースクリプト、ホストの ~/.claude/ をセッションに対して読み取り専用にします。イメージに組み込むか、読み取り専用でマウントしてください。
• ディスパッチには環境ごとのアクセス制御がない：Anthropic 組織のすべてのメンバーは、セッションを任意の環境にディスパッチできます。Owner が Claude Tag チャネルを環境にルーティングする場合、Claude Tag アクセス設定が許可するすべてのユーザーがそこで実行されるチャネルセッションを開始できます。デフォルトでは、Claude アカウントの有無に関わらず、接続された Slack ワークスペース内のすべてのユーザーです。すべてのランナーホストを、それにディスパッチできるすべてのユーザーがコード実行に到達可能として扱い、ランナーホストには、それらのユーザーすべてが読み取ることを許可されているデータと認証情報のみを配置してください。--lock-to-account は、特定のホストが実行するアカウントのセッションを制限しますが、環境にディスパッチできるユーザーを絞り込みません。セルフホスト環境を唯一のピッカーオプションにするには、Owner が Cloud environments ページから組織全体の Anthropic ホスト環境を非表示にできます。
• リポジトリ設定ガードを適用する：--confine-repo-settings でガードモードを選択してください。デフォルトの warn は違反をログに記録してもセッションを生成し、enforce はセッションを拒否し、off はスキャンを無効にします。ランナーは各リポジトリのコミットされた設定をスキャンして、次の項目を検出します：
  • そのセッション独自のワークスペースの外で解決される付与：additionalDirectories エントリ、permissions.allow の Edit、Write、または NotebookEdit ルール、または sandbox.filesystem.allowWrite または allowRead エントリ
  • 空でない env ブロック
  • sandbox.enabled: false などのオペレーター姿勢の上書き
  ガードは --trust-workspace に関係なく実行され、リポジトリフック、.mcp.json、または Bash ルールはカバーしません。権限とツール承認では、これらの付与がどこに属するかについて説明しています。

​

ネットワーク要件

• statsig.anthropic.com、*.sentry.io、claude.ai、platform.claude.com：これらのホストは一部の古いエンタープライズネットワークチェックリストに記載されていますが、ランナーはこれらに到達しません。機能フラグのフェッチは api.anthropic.com に送られ、ランナーはインタラクティブ OAuth ではなく環境シークレットで認証します。
• mcp-proxy.anthropic.com：セルフホストセッションはこれを使用しません。組織でコネクタ配信が有効な場合、組織の claude.ai コネクタは api.anthropic.com を通じてセッションに届きます。MCP サーバーを参照してください。

• ワンラインインストーラー：インストール時に claude.ai から install.sh をフェッチします。
• インタラクティブな claude auth login：claude.ai、claude.com、platform.claude.com を通じてサインインします。ガイド付きセットアップ、doctor のサインイン済みモード、CI ディスパッチがこれを使用します。サインインに使用するブラウザーは、claude.ai サインインページのブラウザーチェックも hcaptcha.com、*.hcaptcha.com、challenges.cloudflare.com から読み込みます。組織でシングルサインオンを使用している場合、そのブラウザーは sso.claude.com 経由でリダイレクトされることもあります。

​

デフォルト拒否出力

​

出力プロキシに認証する

​

Proxy-Authorization 値の出所を選択する

• --proxy-authorization-command <command>：オンデマンドで生成するトークンの場合はこれを選択してください。ランナーはシェルコマンドを実行し、トリミングされた stdout をヘッダー値として使用します。例えば Bearer <token>。
• --proxy-authorization-file <path>：別のプロセスがローテーションするトークンの場合はこれを選択してください。ランナーはファイルを読み取り、トリミングされた内容をヘッダー値として使用します。

​

ランナーが起動を拒否する設定

• 両方のフラグが設定されている：1 つのフラグと他のフラグの環境変数は、両方を設定することとしてカウントされます。
• プロキシ URL がない：HTTPS_PROXY も HTTP_PROXY も http:// または https:// URL を保持していません。ランナーは両方の変数を大文字または小文字で読み取り、ALL_PROXY を参照しません。
• フラグがオーケストレーターサブコマンドに渡される：self-hosted-runner orchestrator はフラグまたはそれらの環境変数を受け入れません。代わりに、オーケストレーターが開始する各ランナーにフラグを渡してください。

​

プロキシ認可フラグが設定されている間にランナーが変更する内容

• リスナー：リスナーは 127.0.0.1 上のフォワードプロキシです。ランナーはコントロールプレーンに登録する前にリスナーを開始し、リスナーが開始できない場合は起動時に終了します。
• プロキシ変数：ランナーは、設定した HTTPS_PROXY と HTTP_PROXY のいずれかをリスナーを指すように書き直します。その書き直された値はランナー自体、ライフサイクルフック、実行するすべてのセッションに到達します。
• トークンローテーション：ローテーションされたトークンは再起動なしで有効になります。リスナーがプロキシに開く各接続について、ランナーはコマンドを実行するか、ファイルを再度読み取り、結果をヘッダーとして追加します。
• セッション環境：セッションはリスナーを通じてのみプロキシに到達します。各セッションの環境で、ランナーは ALL_PROXY を削除し、設定しなかった HTTPS_PROXY または HTTP_PROXY のスペルを削除し、NO_PROXY をランナー独自の値にピンします。
• ログ：ランナーはヘッダー値をログに記録しません。

​

git を設定する

• ランナーに git を設定させる：--configure-git でランナーを開始して、Anthropic ホストセッションが使用する同じ ID とコミット署名設定を書き込ませます
• イメージに git 設定を含める：ID とプッシュ認証情報を自分で設定します。例えば、独自のボット ID でコミットするため

​

ランナーに git を設定させる

• user.name = Claude および user.email = noreply@anthropic.com。Anthropic ホストセッションと一致します
• SSH 形式のコミットとタグ署名。ランナー管理のシムを通じてルーティングされ、セッション独自の認証情報を使用して Anthropic の署名サービスを通じて各コミットに署名します。署名は GitHub で Anthropic の公開 SSH 署名キーに対して検証可能です。
• push.negotiate = true。git がプッシュをパックする前に git ホストが既に持っているコミットを尋ねます。Claude Code v2.1.257 以降が必要です。
• core.hooksPath はランナー管理のフックディレクトリを指します。その commit-msg および prepare-commit-msg フックは、各コミットにセッションの作成者の Co-authored-by: トレーラーを追加します。CCR_SESSION_ACCOUNT_EMAIL のメールから構築され、その変数が設定されていない場合は省略されます。イメージが既に core.hooksPath を設定していて、ランナーが Anthropic 管理の git を使用していない場合、ランナーは設定を保持し、これらのフックのインストールをスキップし、[runner:git] 警告を出力します。

​

イメージに git 設定を含める

RUN git config --system user.name "Claude" && \
    git config --system user.email "noreply@anthropic.com"

• url.<base>.insteadOf 書き直しで 1 つのリポジトリに制限された SSH デプロイキー
• 最小限のスコープトークンを返す credential.helper
• 狭くスコープされたキーを指す GIT_SSH_COMMAND

• ランナーは GIT_TERMINAL_PROMPT=0 を設定するため、git はユーザー名またはパスワードを要求しません。
• ランナーは BatchMode=yes で SSH を実行します。GIT_SSH_COMMAND を設定した場合は追加されます。SSH はパスフレーズまたはホスト確認を要求しません。
• ランナーは GCM_INTERACTIVE=never を設定するため、Git Credential Manager はサインインダイアログを開きません。
• ランナーは core.askPass をクリアするため、askpass ヘルパーを使用する場合は、GIT_ASKPASS 環境変数を通じて設定してください。

RUN git config --system --add safe.directory '*'

​

Anthropic git プロキシを使用する

• github.com のみ：Anthropic は、セッションのすべてのリポジトリが github.com 上にある場合にのみそのセッションを提供します。また、git プロキシはまだ GitHub Enterprise Server をサポートしていません。git プロキシを使用するランナーでは、別の git ホスト上のリポジトリを持つセッションは開始に失敗します。
• セッションのリポジトリのみの認証情報：Anthropic は、セッションに含まれるリポジトリに対して git 認証情報を提供し、同じ git ホスト上の他のリポジトリに対しては提供しません。プライベートサブモジュール、パッケージマネージャーが git で取得する依存関係、または別のリポジトリにあるプラグインマーケットプレイスは、Anthropic から認証情報を受け取りません。セッションを作成するユーザーに、作成時にセッションが必要とするすべてのリポジトリを追加するよう依頼してください。 クラウドスケジュールタスクの各実行は、そのタスクのリポジトリを持つセッションです。そのため、各タスクの所有者に、実行に必要なすべてのリポジトリを追加するよう依頼してください。
• ブランチへのプッシュのみ：ブランチを削除するプッシュは失敗し、タグなど他の種類の ref へのプッシュも失敗します。プッシュで更新できるブランチについては、GitHub プロキシを参照してください。
• 接続済みの GitHub アカウント：リポジトリを含むユーザーセッションを作成する各ユーザーに、GitHub を接続するよう依頼してください。本人の接続がない場合、それらのセッションは開始されません。
• --capacity 1：git プロキシはランナープロセスごとに 1 つのセッションを必要とするため、並列処理のためにより多くのレプリカを実行してください。要件は Anthropic git プロキシをオンにするに記載されています。
• グローバル git 設定の置き換え：ランナーは、実行ユーザーのグローバル git 設定を削除して置き換えます。専用ユーザーとして、またはコンテナ内で実行してください。
• ホストからのプッシュにはホストの認証情報：ランナーの --push-outcome-on-release によるプッシュと、post-session フックが行うプッシュは、引き続きランナーホスト独自の git 認証情報と github.com へのネットワーク経路を使用します。これらの認証情報はグローバル git 設定に置かないでください。提供方法についてはイメージに git 設定を含めるを参照してください。
• セッションごとの判断：Anthropic はランナー上の各セッションについて git を提供するかどうかを決定し、提供されないセッションは開始に失敗します。原因については git プロキシを使用するランナーでセッションの開始に失敗する場合で説明しています。

​

Anthropic git プロキシをオンにする

• Claude Code v2.1.267 以降：それより前のバージョンはフラグを受け入れますが、Anthropic に git の提供を求めるリクエストを報告せず、Registering as opted in 行も出力しないため、Anthropic はそれらのセッションを提供しません。
• --capacity 1（デフォルト）：各ランナープロセスは一度に 1 つのセッションを処理するため、並列処理のためにより多くのレプリカを実行してください。
• Git 2.32 以降：古い git は、ランナーが git プロキシ用に設定するセッションごとの git 設定を無視します。

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>' --use-anthropic-git-proxy

​

Anthropic がセッションの git を提供する仕組み

• ユーザーセッション：Anthropic はセッション作成者用に保存された GitHub OAuth トークンを使用します。
• ボットおよびエージェントセッション：Anthropic は組織の GitHub App インストールトークンを使用します。
• URL の書き直し：--git-host-rewrite と --git-ssh-rewrite は、git プロキシが提供するリポジトリには効果がありません。

​

git プロキシを使用するランナーでセッションの開始に失敗する場合

• governed git ACTIVE も withheld 行もない：Claude Code v2.1.267 より古いランナーはどちらの行もログに記録せず、Anthropic はそのセッションを提供しません。バージョンを固定するの手順に従って、ランナーを v2.1.267 以降に更新してください。
• withheld 行：Anthropic はセッションを提供しませんでした。以前は git プロキシで動作していたランナーでも、ユーザー側で何も変更していないのにこのように失敗することがあります。
  • github.com 上にないリポジトリがある：GitHub Enterprise Server など別の git ホスト上のリポジトリが 1 つでもあるセッションは、その github.com リポジトリも含めて提供されません。その環境のランナーでは Anthropic git プロキシをオフにしてください。
  • すべてのリポジトリが github.com 上にある：withheld 行のセッション ID を添えて、Anthropic アカウントチームに失敗を報告してください。Anthropic は理由を自社側で記録しています。
• remote: access denied by the git proxy を含む行：Anthropic が提供するセッションでも拒否される場合があります。たとえば、組織のポリシーがセッションの git アクセスを拒否する場合や、セッションがリポジトリに対して認可されていない場合です。その場合、ランナーのログに remote: access denied by the git proxy を含む行が表示され、その行の残りの部分に理由が示されます。
• GitHub authentication required：セッションの作成者が claude.ai で有効な GitHub 接続を持っていない場合に表示されます。セッションのクローンは失敗し、git エラーには GitHub authentication required. Please reconnect your GitHub account. と表示されます。そのユーザーに、claude.ai の設定で GitHub を接続または再接続するよう依頼してください。

​

Anthropic git プロキシをオフにする

unset CLAUDE_RUNNER_USE_GIT_PROXY

​

GitHub CLI なしで GitHub API にアクセスする

gh api repos/{owner}/{repo}/pulls -f title='Fix' -f head='my-branch' -f base='main'

• 認証情報：組み込みの gh は REST リクエストを Anthropic 管理の git 経由で送信し、GitHub の認証情報は Anthropic 側で提供されるため、イメージにそのための GitHub トークンは不要です
• 利用できるセッション：Anthropic 管理の git がセッションの gh を提供するかどうかは、Anthropic がセッションごとに決定します。提供する場合、ランナーがそのセッションについてログに記録する [runner:session] governed git ACTIVE 行に gh_path_shim=true が表示されます。提供しない場合、そのセッションには gh がありません
• jq：--jq を使用したい場合は、イメージに jq をインストールしてください
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：セッション環境でこれが設定されている場合、Claude Code は組み込みの gh を提供せず、セッションには gh がありません

​

Anthropic 管理の git でプライベート認証局を信頼する

• システム証明書ストア：ランナーホストのシステム証明書ストアに CA をインストールし、git は変数なしでそれを信頼します。
• GIT_SSL_CAINFO：CA の PEM ファイルに設定します。例えば GIT_SSL_CAINFO=/etc/ssl/corp-ca.pem。
• GIT_SSL_NO_VERIFY：再署名プロキシの背後では役に立ちません。Anthropic 管理の git を通じたランナー独自のクローンは、変数が設定されている場合でも証明書をチェックするため、git が他の 2 つのアプローチのいずれかを通じて CA を信頼するまで、そのクローンは失敗します。

• GIT_SSL_CAINFO：git が Anthropic 管理の git に対してチェックするものは、git が実行される場所によって異なります：
  • ランナー独自のクローンとフェッチ：変数なしで実行され、ランナーが書き込むセッションごとの証明書ファイルに対して Anthropic 管理の git をチェックします。ランナーは、ランナーホストのシステム CA バンドルと指定したファイル内の証明書からそのファイルを作成します。
  • セッション内の git：変数の代わりに http.sslCAInfo 設定を取得し、ファイルに名前を付けます。また、セッションごとのファイルに対して Anthropic 管理の git をチェックする http.<url>.sslCAInfo エントリを取得します。
  • checkout および post-session フック：変数を変更されずに継承します。
• GIT_SSL_NO_VERIFY：証明書チェックが無効のままであるかは、git が実行される場所によって異なります：
  • ランナー独自のクローンとフェッチ：変数なしで実行され、提示される証明書をチェックします。
  • セッション内の git：変数の代わりに http.sslVerify=false 設定を取得するため、他のホストのチェックは無効のままです。また、Anthropic 管理の git のチェックを有効に保つ http.<url>.sslVerify=true エントリを取得します。
  • checkout および post-session フック：セッションが Anthropic 管理の git 上のリポジトリを持つ場合、変数の代わりに http.sslVerify=false 設定を取得します。また、Anthropic 管理の git のチェックを有効に保つ http.<url>.sslVerify=true エントリを取得します。

​

Claude Tag チャンネルのセッションに github.com のリポジトリを追加する

​

プライベートネットワークの git URL を書き直す

• --git-host-rewrite <from>=<to>：スプリットホライズン DNS の場合。Anthropic は外部ホスト名を通じて git ホストに到達しますが、ランナーは内部ホスト名を使用する必要があります
• --git-ssh-rewrite <host>：SSH のみを受け入れる git ホストの場合、または SSH キーしか持たないランナーホストの場合。例えば、github.com のリポジトリを SSH でクローンするには、ランナーのコマンドに --git-ssh-rewrite github.com を追加します。するとランナーは https://github.com/owner/repo を git@github.com:owner/repo に書き直します。SSH はプロンプトなしで接続できる必要があります。

​

ランナーイメージをビルドする

FROM debian:bookworm-slim
ARG CLAUDE_CODE_VERSION
RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq \
 && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \
      -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude
RUN git config --system user.name "Claude" \
 && git config --system user.email "noreply@anthropic.com" \
 && git config --system --add safe.directory '*'
ENTRYPOINT ["claude"]

docker build \
  --build-arg CLAUDE_CODE_VERSION="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \
  -t <your-registry>/claude-runner:latest .

​

セッション用に CPU とメモリをサイズ設定する

• メモリ: 各 4 GiB のリクエストと制限。これは Claude Code のシステム要件の 4 GB 最小値を満たします。2 つを等しく保つことで、スケジューラーはコンテナの全メモリを考慮に入れます。コンテナがメモリ制限に達すると、カーネルはその内部のプロセスを強制終了し、セッションをタスクの途中で終了させる可能性があります。
• CPU: 2 CPU のリクエストと 4 CPU の制限。セッションはビルド中にリクエストを超えてバースト可能です。カーネルはコンテナを CPU 制限でスロットルします。その制限でプロセスを強制終了するのではなく、セッションは制限で実行速度が低下しますが、実行を続けます。

resources:
  requests:
    cpu: "2"
    memory: 4Gi
  limits:
    cpu: "4"
    memory: 4Gi

• ランナーあたり 1 つのセッション: 各コンテナに 1 つのセッションの値を与えます。強化セクションが推奨する --capacity 1 でこのサイズ設定を使用し、オンデマンドランナーの場合、spawn-runner フックが送信するワークロード（Kubernetes Job のポッドテンプレートなど）に値を設定します。
• ランナーあたり複数のセッション: --capacity が 1 より上の場合、1 つのセッションの値に容量を掛けます。その容量まで多くのセッションがコンテナ内で同時に実行できるためです。Kubernetes と Docker Compose レシピは CPU またはメモリ制限なしで --capacity 4 を実行するため、実行する容量のサイズ設定された制限を追加してください。
• 1 つのホスト上の複数のランナーコンテナ: 各ランナーは自身のセッションのみを --capacity に対してカウントするため、ランナーの容量の合計に合わせてホストをサイズ設定します。
  • メモリ: 1 つのセッションのメモリに合計を掛け、ホスト自身のプロセスが使用する分を加えます
  • CPU: 1 つのセッションの CPU リクエストに合計を掛けます。すべてのセッションが同時にバーストできるようにするには、代わりに CPU 制限を掛けます。
  各ランナーに専用のコンテナを与えてください。各ランナーが専用の作業ディレクトリを持つように、それぞれで同じ --base-dir パスを、他のランナーのコンテナがマウントしないストレージ上で使用してください。

​

各セッションに専用のメモリ制限を与える

• コンテナ内: コンテナあたり 1 つのランナーを実行し、コンテナのメモリ制限を設定します。例えば Kubernetes では limits.memory、Docker では --memory、Compose ファイルでは mem_limit です。コンテナの制限の合計はホストのメモリ未満に保ってください。ホスト自体のメモリが不足すると、カーネルはホスト上のどこにあるプロセスでも強制終了する可能性があるためです。
• コンテナなしの systemd 下: ランナーのユニットに MemoryMax を設定し、ホストあたり 1 つのランナーを実行します。1 つのファイルシステム上で同じ --base-dir を使用するランナーは、そこにクローンされたリポジトリを共有するためです。例えば、checkout フックなしの --capacity 1 では、1 つのリポジトリ上のそれらのセッションが同じチェックアウトで同時に作業する可能性があります。1 つのホストで複数のランナーを実行するには、それぞれにコンテナを与えてください。

​

プロセスとスレッドの制限に余裕を残す

​

各制限の設定場所

​

1 つのセッションのピークを測定する

​

pids.max 制限を確認する

• pids.max に達したかどうかを確認する: 例えば dmesg を使って、ホストのカーネルログで cgroup: fork rejected by pids controller in と cgroup のパスを含む行を検索します。カーネルはその cgroup で最初にプロセスまたはスレッドを拒否したときにのみログに記録するため、ログ全体を検索してください。
• 適用中の制限を確認する: ランナーの cgroup ディレクトリとその上位の各ディレクトリで pids.max を読み取ります。最も低い値が適用中の制限で、max はそのレベルで制限がないことを意味します。

​

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-runner
  namespace: claude-runners
spec:
  replicas: 3
  selector:
    matchLabels:
      app: claude-runner
  template:
    metadata:
      labels:
        app: claude-runner
        app.kubernetes.io/part-of: claude-code-self-hosted-runner
    spec:
      terminationGracePeriodSeconds: 90
      containers:
        - name: runner
          image: <your-registry>/claude-runner:latest
          args:
            - self-hosted-runner
            - --environment-secret-file
            - /etc/claude/environment-secret
            - --capacity
            - "4"
            - --base-dir
            - /workspace
          volumeMounts:
            - name: environment-secret
              mountPath: /etc/claude
              readOnly: true
          ports:
            - name: health
              containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 30
      volumes:
        - name: environment-secret
          secret:
            secretName: claude-runner-environment-secret

kubectl create namespace claude-runners

kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

​

Docker Compose

services:
  claude-runner:
    image: <your-registry>/claude-runner:latest
    command:
      - self-hosted-runner
      - --environment-secret-file
      - /run/secrets/environment-secret
      - --capacity
      - "4"
      - --base-dir
      - /workspace
    secrets:
      - environment-secret
    restart: always
    stop_grace_period: 90s

secrets:
  environment-secret:
    file: ./environment-secret

​

シャットダウンタイミング

1. ランナーは、まだ実行中のターンが終了するのを最大 --drain-wait-sec 秒（デフォルトは 0）待機します。
2. 各セッションのプロセスツリーを終了します。これには Claude がまだ実行していたコマンドも含まれますが、シェルコマンドの終了後も実行し続けているプロセスは含まれません。
3. post-session ライフサイクルフックを実行します。

• ステップ 1 の --drain-wait-sec（デフォルトは 0 秒）
• ステップ 2 の --session-stop-grace-sec（デフォルトは 5 秒）
• ステップ 3 の --post-session-hook-timeout-sec（デフォルトは 60 秒）
• 固定の 15 秒の余裕
• --push-outcome-on-release が設定されている場合はさらに 30 秒

• --retire-at を使用する場合：リタイア時刻とホストが停止する時刻の間に、典型的なターンが終了するのに十分な時間、ランナーのライフサイクルで説明されているバックグラウンドタスクの待機時間、およびログに記録された時間を確保してください。リタイア時刻は起動のたびに計算します。例えば date +%s にランナーの想定稼働時間を加えます。
• --defer-shutdown-max-min を使用する場合：停止タイムアウトには、設定した分数と、ドレイン開始前のさらなる待機時間（デフォルト設定では 75 秒）も含める必要があります。両方については最初のシグナルを超えてドレインを遅延させるで説明しています。ランナーはこの長い時間も起動時にログに記録します。

​

再起動の前に実行中のターンを終了させる

• --drain-wait-sec：終了させたいターンとバックグラウンドタスクにかかる時間と同程度に設定します。これは最大値です：それらが先に終了した場合、待機は早めに終わります。
• 停止タイムアウト：Kubernetes では terminationGracePeriodSeconds、Docker Compose では stop_grace_period です。例えば --drain-wait-sec 120 の場合、Kubernetes または Docker Compose のレシピの 90 を 200 に置き換えます。
• 他のシャットダウン設定を変更した場合：80 秒はデフォルト設定の場合の値です。使用するフラグで 1 つのランナーを起動し、起動時の行 This runner needs up to に示される数値（待機時間を含みます）以上を使用してください。--defer-shutdown-max-min を設定している場合は、次の起動時の行で Size the stop timeout to at least の後に示される、より大きい数値を使用してください。これらの数値に加算される要素はシャットダウンタイミングに記載されています。

​

再起動の前にステータスメッセージを投稿する

​

最初のシグナルを超えてドレインを遅延させる

​

最初のシグナル後にランナーが保持するセッションに何が起こるか

• 最初の n 分間：ランナーは通常セッションを提供し、--startup-timeout-min と --kill-session-after-min を適用し続けます。--release-idle-session-minも設定した場合、ランナーはユーザーがその時間アイドル状態だったセッションをリリースします。それなしでは、アイドルセッションはランナーに留まります。
• n 分が経過したとき：ランナーは、アイドルかどうかにかかわらず、まだ保持しているすべてのセッションをリリースします。ランナーはターン途中のセッションのターンが終了するのを待ち、ターンのバックグラウンドタスクのためにさらに最大 60 秒待ってから、そのセッションをリリースします。
• リリース後の猶予が経過したとき：ランナーはまだ保持しているセッションをドレインし、コントロールプレーンは各ドレインされたセッションを別のランナーにすぐに再キューイングします。リリース後の猶予は n 分が経過したときに開始され、デフォルトでは 75 秒です。--drain-wait-sec を 60 秒より大きく設定した場合、リリース後の猶予は代わりに --drain-wait-sec + 15 秒になります。

​

停止タイムアウトをサイズ設定する

​

実行中の post-session フックに到達するもの

• ランナーが既にドレイン中の SIGTERM：ランナーを直ちに強制終了し、ドレインの残りをスキップします。--defer-shutdown-max-minなしでは、ランナーが受け取る 2 番目の SIGTERM です。実行中の post-session フックにはシグナルが送信されないため、init プロセスが孤児プロセスを引き取るベアホストでは、フックは独自に終了しますが、監視されていません：タイムアウト予算はもはや適用されず、閉じたログパイプへの書き込みによって SIGPIPE で強制終了される可能性があるため、そこで強制終了から生き残る必要があるフックは独自の出力をファイルにリダイレクトする必要があります。このページのコンテナレシピでは、ランナーはコンテナの PID 1 であり、その終了はコンテナを終了させます。また systemd のデフォルト KillMode=control-group の下では、Cgroup 全体のキルの項目で説明するように、cgroup 全体のキルがフックにも到達します。どちらの場合も、強制終了をフックにとって致命的なものとして扱い、代わりに猶予期間に依存してください。
• プロセスグループ全体のシグナル（ラッパースクリプト内の kill -- -<pid>、シェルのジョブ制御、グループ全体のウォッチドッグなど）：ランナーと、checkout フック実行中のサブプロセス（意図的にグループに接続されたままです）に到達しますが、実行中の post-session フックやセッション子には到達しません。
• Cgroup 全体のキル（systemd のデフォルト KillMode=control-group や、terminationGracePeriodSeconds が期限切れになったときに Kubernetes がコンテナ全体に送信する SIGKILL など）：フックを含むすべてに到達します。プロセスグループの分離ではこれらから保護できないため、猶予期間はドレイン全体をカバーする必要があります。
• フック独自のタイムアウト：フックが --post-session-hook-timeout-sec を超えると、ランナーはフックの全体プロセスグループに SIGTERM を送信し、2 秒後に SIGKILL を送信します。フックがフォークしたワーカー（tar、rsync、git など）はラッパーシェルと一緒に終了し、孤児として生き残りません。ランナーの監視は、フックの stdio が閉じたときに終了します：独自の出力をファイルにリダイレクトし、SIGTERM ステージを超えて生き残るワーカーはランナーの到達範囲を超えています。

​

ベースディレクトリと容量をランナー全体で同じに保つ

​

事前にウォームアップされたチェックアウトを再利用する

• --capacity 1 の場合: ランナーは要求された ref をフェッチし、HEAD をデタッチして、それにハードリセットします。これは変更がほとんどない場合、ほぼ瞬時に完了します。
• --capacity が 1 より大きい場合: ランナーはそのクローンにフェッチし、セッションごとにそこから個別の worktree をチェックアウトします。事前にウォームアップされたクローンによってダウンロードは省略されますが、チェックアウトは省略されません。

• イメージ内にクローンを配置する: ランナーイメージをそのパスにビルドしてクローンを含めます。その後、新しいコンテナはすべてディスクを再利用せずにウォームクローンで起動します。
• 永続ボリューム上にクローンを配置する: --lock-to-account で 1 人のユーザーアカウントにプリロックされたランナーで、--base-dir を永続ボリュームに指定すると、ディスクはそのアカウントのみを提供します。プリロックされたランナーは Claude Tag チャネルセッションを取得しないため、このオプションはそれらを提供するランナーには適用されません。

• クローンの深さ: クローンは --depth なしでビルドしてください。--single-branch の有無は問いません。ランナーは origin リモートを持つクローンにフェッチするとき、CLAUDE_RUNNER_FETCH_DEPTH を設定していても --depth を渡しません。完全なクローンでは、各セッションはクローンに欠けているコミットのみをダウンロードします。シャロークローンでは、クローンの最も古いコミットより前に分岐したブランチ上のセッションは、そのブランチの履歴全体をダウンロードします。
• 追跡された変更はリセットされ、追跡されていないファイルは保持される: --capacity 1 では、各セッションはハードリセットから開始され、前のセッションの追跡された変更を削除しますが、ランナーは git clean を実行しないため、ロックされたオーナーの以前のセッションからの追跡されていないファイルはツリーに残ります。
• セッションごとのディレクトリも保持される: チェックアウトの横に、ランナーは実行するすべてのセッションに対して <base-dir>/_sessions/ の下にセッションごとのエントリを作成します。セッションの Claude 設定ディレクトリは、会話トランスクリプトのローカルコピーを保持します。その横には、セッションがある場合、セッションのアップロードされたファイルが配置されます。セッションディレクトリもそこに配置されます。セッションの実行中、セッションごとの worktrees と checkout フックチェックアウトを保持し、Claude がそこに書き込んだ他のすべてのものを保持します。 デフォルトでは、ランナーはセッションが終了したときにこれらをそのまま残すため、ランナープロセスより長く存続するディスク上に蓄積されます。すべてのセッションはランナー自身のユーザーとして実行されるため、そのディスクが提供する後続のセッションはそれらを読み取ることができます。永続的な --base-dir を保持する場合は、その成長に対応するようにボリュームのサイズを設定してください。同じことは、Docker Compose レシピ を含む、同じファイルシステム上でランナーを再起動するすべてのセットアップに適用されます。
• --remove-session-state を使用する場合、セッションごとのディレクトリは保持されない: --remove-session-state でランナーを起動して、セッションが終了するときに各セッションのセッションごとのディレクトリを削除させます。削除はベストエフォートです。ランナーがクリーンアップ実行前に強制終了された場合、ディレクトリは残ります。正規クローンとセッションがホスト上の他の場所（一時ディレクトリなど）に書き込んだファイルは、いずれにせよ残ります。
• git プロキシを使用する場合、リセットはチェックアウトになる: --use-anthropic-git-proxy を使用すると、ランナーは各セッションの前にクローンの .git/ をサニタイズします。オブジェクトストアとシャロー状態は保持し、インデックスは削除します。インデックスがないため、各セッションはほぼ瞬時のリセットではなく、完全なワーキングツリーチェックアウトから開始されます。それでもランナーは、リポジトリを再度クローンするのではなく、既存のクローンにフェッチします。プロキシの下ではサブモジュールプリウォームはサポートされていません。
• git プロキシを使用する場合、reftable のプリウォームは ref を失う: ランナーは各セッションの前に .git/ をサニタイズする際、.git/refs/ を保持し、.git/reftable/ ディレクトリを削除します。git の reftable ref 形式でプリウォームされたクローンはこの処理によって ref を失うため、代わりに git の files ref 形式でクローンをプリウォームしてください。
• 長いクローンは回避策を必要としない: ランナーは各 git 操作を 120 秒の無進捗ウォッチドッグと 30 分のハードキャップで制限し、フラットタイムアウトではないため、進捗を報告し続けるスローコールドクローンは完了します。

​

ランナーがクローンを使用していることを確認する

​

バージョンをピンする

• バージョンをピンする前に：セッションが使用するすべてのモデルについて モデルが必要とする Claude Code バージョン を確認してください。モデルがセッションで実行されるバージョンより新しいバージョンを必要とする場合、サーバーはそのモデルのリクエストを Claude Code does not support this model で拒否します。
• フリートを 1 つのバージョンに保持するには：ピンされたバージョンでイメージをビルドするか、ベアホストで特定のバージョンをインストールし、オートアップデートを無効にしてください
• 固定フリートをアップグレードするには：現在のバージョンとインストールするバージョンの間の changelog のエントリを確認してから、新しいバージョンをインストールするか、イメージを再ビルドしてランナーを再起動してください
• オンデマンドランナーをアップグレードするには：現在のバージョンとインストールするバージョンの間の changelog のエントリを確認してから、spawn-runner フックが起動するイメージを変更してください。新しいランナーにはそれぞれ新しいバージョンが適用されます。すでに起動しているランナー（--min-idle によって起動されたスタンバイランナーを含む）は、終了するまでそのバージョンを維持します。その作業指示は一度しか使用できないため、再起動しないでください。
• セッションが別のバイナリを起動する場合：--exec-path または command フックを使用してランナー独自のもの以外の Claude Code バイナリを起動する場合、セッションはそのバイナリのバージョンを実行します。ランナーをアップデートするときは、そのバイナリもアップデートしてください。
• プラグイン：プラグインマーケットプレイスもオートアップデートしません。ランナーの環境で FORCE_AUTOUPDATE_PLUGINS=1 を設定して、バイナリがピンされたままの間、プラグインをオートアップデートさせます

​

フリートをスケーリングする

• 固定フリート: 静的なランナーレプリカセットを実行し、各ランナーが提供する Prometheus メトリクスに基づいてスケーリングします
• オンデマンドランナー: claude self-hosted-runner orchestrator サブコマンドを実行します。このコマンドは、利用可能なランナーがないキューに入っているセッションについて Anthropic をポーリングし、spawn-runner フックを呼び出して、セッションごとに 1 つ起動します。オンデマンドランナーを参照してください。

​

固定フリートでアイドル状態のセッションを解放する

• その時間を超える系列（30 分の場合の 1800 など）: アイドル状態のセッションがそれらのスロットを保持しているため、--release-idle-session-min を設定します
• すべての系列がその時間未満: それほど長くアイドル状態のセッションはありません。ランナーを追加するか、アイドル状態にならないセッションのために --kill-session-after-min を設定します。
• 系列がないランナー: そのランナーを保持しているセッションはありません。トラブルシューティングの Sessions stay queued を参照してください。
• メトリクスが応答しないランナー: プロセスが終了している可能性があります。ランナーが終了したときの An environment that looks healthy を参照してください。

• プッシュされていない作業: 解放されたセッションは次のメッセージで再開されますが、プッシュしていなかった作業は失われます。コミットを保持するには、再開されたセッションはプッシュされていない作業を失うを参照してください。
• ランナーの終了: 最後のセッションを解放したランナーは通常の終了を開始します。デプロイを強化するで説明しているように、スーパーバイザーが新しいファイルシステム上でランナーを再起動するようにしてください。
• アイドル状態にならないセッション: 一部のセッションはアイドル状態としてカウントされないため、--kill-session-after-min も設定します

​

既知の問題と制限事項

​

コネクタのトラフィックはネットワーク外に出る

• https://api.anthropic.com/v2/ccr-sessions/*
• https://api.anthropic.com/v1/code/sessions/*
• https://api.anthropic.com/v1/code/mcp/*

​

一部のセッションはアイドルとみなされない

• セッションがユーザーを待っている場合、ランナーはそのセッションを解放します。ターンが終了していてバックグラウンドタスクのみを保持している場合、ランナーはそれらのタスクが完了するまで最大 60 秒待ってから、セッションを解放します。セッションは、ユーザーが次のメッセージを送信すると再開されます。
• ターンがまだ実行中の場合、ランナーはターンが完了するか、セッションが次にユーザーを待つ状態になるまで待ってから、セッションを解放します。
• 猶予期間が終了した時点でセッションがまだランナー上にある場合、ランナーはセッションを終了し、実行中のターンの作業は失われます。実行中のツール呼び出しの内部から要求された承認をターンが待っている場合は、セッションが猶予期間を超えて残る一例です。

​

その他の制限事項

• 再開されたセッションではプッシュしていない作業が失われる: 新しいランナーはリポジトリを開始ブランチから再度クローンするため、セッションがプッシュしていなかった作業は失われます。
  • コミット済みの作業を保持するには: 環境内のすべてのランナーで --push-outcome-on-release を設定してください。このフラグのないランナーは、セッションを開始ブランチから再開するためです。このフラグを設定したランナーは、解放する前にセッションの成果ブランチのプッシュをベストエフォートで行い、再開されたセッションはそれらのコミットから開始されます。プッシュにはランナーホスト自身の git 認証情報が使用されます。これは Anthropic 管理の git を使用するランナーでも同様です。
  • checkout フックを使用する場合: checkout ライフサイクルフックでチェックアウトされたリポジトリはプッシュされません。代わりに post-session フックからそれらのスナップショットを取得してください。
  • フラグを有効にする前に: ソースリモート上の claude/* ref にプッシュできるユーザーを制限してください。再開時、ランナーは以前にプッシュされたブランチを、誰がプッシュしたかを検証せずにフェッチします。
  • コミットされていない変更は引き続き失われる: Claude が応答を終えたときにコミットとプッシュを行うよう促すには、セッションに作業のプッシュを促すを参照してください。
• ランナーの喪失によって中断されたコマンドが再度実行されることがある: セッションが別のランナーで再開されると、中断されたツール呼び出しが、その成否が不明であることを示す結果とともに Claude に表示されます。
• セッションの途中で追加したリポジトリのクローンが失敗することがある: Claude は HTTPS 経由の git clone でリポジトリをクローンします。--use-anthropic-git-proxy を使用していないランナーでは、ホスト上にリポジトリを読み取れるものが何もない場合、クローンは git の認証エラーで失敗します。可能であれば、セッションの作成時に、セッションで必要なすべてのリポジトリを選択してください。
• 一部のコネクタがセルフホストセッションに表示されない: claude.ai の設定でまだ接続していないコネクタはセルフホストセッションに表示されず、セッションから接続を求められることもありません。まず設定で接続してから、新しいセッションを開始してください。また、すでに実行中のセッションにコネクタを追加しても、そのツールは Claude で使用できるようになりません。新しく追加したコネクタを反映するには、新しいセッションを開始してください。
• 誰かがセッションをアーカイブまたは削除した場合、またはセッションのメニューからランナーを解放した場合: --push-outcome-on-release によるプッシュは当てにしないでください。このような場合にコミットを保存するには、post-session フックから HEAD を退避用ブランチにプッシュしてください。そこにある例をもとにする場合は、コミットされていない変更が何もないときでもプッシュするように変更してください。この例はスナップショットのコミットを作成した後にのみプッシュするためです。

​

問題を報告する

​

トラブルシューティング

claude self-hosted-runner doctor

• ランナーが環境に表示されない: ホストが HTTPS 経由で api.anthropic.com に到達できること、環境シークレットが最新であること、ホストの時計と実時間との差が 5 分以内であることを確認してください。それより大きなずれがあると認証が失敗します。認証に失敗すると、ランナーは拒否理由とともに [runner:fatal] をログに記録します。
• ランナーが起動時に cannot create or write to base directory で終了する: ランナーが --base-dir（デフォルトは /workspace）を作成できないか、書き込めません。ランナー間でベースディレクトリと容量を同一に保つで説明しているとおり、ディレクトリの所有権を修正するか、--base-dir を書き込み可能なパスに向けてください。代わりにランナーがベースディレクトリのチェックがタイムアウトしたという [runner:fatal] をログに記録する場合、そのディレクトリはハングした NFS または CSI マウント上にあります。権限ではなくマウントの健全性を確認してください。ランナーはこれら 2 つの起動時の失敗を --log-file を開く前に stderr に出力するため、ログファイルではなくターミナルまたはプラットフォームのコンテナログで探してください。v2.1.225 より前は、ランナーは起動時にベースディレクトリをチェックしておらず、この設定ミスがあると代わりにピックアップ後にセッションが失敗していました。
• ランナーが起動時に RegisterRunner failed: と TLS 証明書エラーで終了する: エラーはたとえば self signed certificate in certificate chain となることがあります。TLS を検査するプロキシの背後にある場合のように、ランナーが受け取った証明書の背後にある認証局（CA）を信頼していません。ランナーの環境で NODE_EXTRA_CA_CERTS に、プロキシのルート CA を含む PEM ファイルを設定してください。 セッションはこれを継承するため、セッション用に再度設定する必要はありません。Git はこれを読み取りません。そのプロキシを経由したクローンには、GIT_SSL_CAINFO も設定してください。
• 開始スクリプトが Resource temporarily unavailable を含む書き込みエラーを出力して終了する: スクリプトが、自身が起動する claude self-hosted-runner または orchestrator プロセスと stdout または stderr を共有しており、そのプロセスが共有のパイプまたはソケットをノンブロッキングモードに切り替えています。パイプがいっぱいになると、スクリプトからの書き込みは待機せずにこのオペレーティングシステムのエラーで失敗し、set -e の下ではスクリプトが終了します。 このエラーを止めるには、ランナーまたはオーケストレーターの出力を、スクリプトのユーザーが作成できるファイルに送ってください。それを起動するコマンドに、バックグラウンド化する & より前の位置で >> "$HOME/claude-runner.log" 2>&1 を追加します:
  claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret >> "$HOME/claude-runner.log" 2>&1
  
  スクリプト自身の出力は引き続き以前と同じ場所に出力され、ランナーが stdout と stderr に書き込む内容（起動エラーを含む）はそのファイルに出力されます。--log-file 単体ではなく、このシェルリダイレクトを使用してください。--log-file はログをファイルにミラーリングしますが、ランナーは stdout と stderr への書き込みを続けます。すでに --log-file を渡している場合は、それもそのまま残してください。リダイレクトはそのファイルが受け取る内容を変えないためです。
• オーケストレーターが TLS 証明書エラーとともに poll failed: をログに記録し、再試行を続ける: TLS を検査するプロキシの背後にある場合のように、オーケストレーターが受け取った証明書の背後にある CA を信頼していません。オーケストレーターの環境で NODE_EXTRA_CA_CERTS に、プロキシのルート CA を含む PEM ファイルを設定してください。spawn-runner フックが起動するランナーにも設定してください。 たとえば、行が poll failed: self signed certificate in certificate chain — retrying in 1s で終わることがあり、コロンとダッシュの間に TLS ライブラリの文言が入ります。修正を確認するには、オーケストレーターの /healthz のボディで connected が true であることを確認してください。
• セッションがキューに入ったままになる: すべてのオンラインランナーがそれぞれ別の所有者にロックされている可能性があります。各ランナーの claude_code_self_hosted_runner_locked_account メトリクス、またはその [runner:health] ログ行の locked_account フィールドを確認して、誰がロックしているかを調べてください。どちらも、act.email クレームを含むセッショントークンがランナーに発行された後にのみ所有者のメールアドレスを表示しますが、Claude Tag エージェントのセッションではこのクレームが含まれることはありません。クレームがない場合、ランナーは locked_account 系列を出力せず、locked_account=yes をログに記録します。これはランナーがロックされていることを示しますが、どの所有者にロックされているかは示しません。レプリカを追加するか、既存のランナーがドレインして再起動するのを待ってください。環境がオンデマンドランナーを使用している場合は、代わりにオーケストレーターを確認してください。オンデマンドランナーを参照してください。
• ピックアップ直後にセッションが失敗する: claude.ai/code でセッションを開いてエラーを確認してください。git が認証できなかったことをエラーが示している場合は、ランナーの git 認証情報を確認してください。--use-anthropic-git-proxy 付きで起動したランナーでは、git プロキシを使用するランナーでセッションの開始に失敗した場合を参照してください。 書き込めないベースディレクトリは、セッションを失敗させるのではなく、起動時にランナーを停止させます。このリストの ランナーが起動時に cannot create or write to base directory で終了する の項目を参照してください。
• セッションはピックアップされたが、Claude が最初のメッセージに応答しない: ランナーがプロキシ経由で api.anthropic.com に到達している場合は、セッションの /worker/events/stream レスポンスを到着したとおりに通過させるようにプロキシを設定してください。ランナーのタイムアウトを引き上げても解決しません。ランナーのログで原因を確認するには、セッションはピックアップされたが、Claude が最初のメッセージに応答しないを参照してください。
• --use-anthropic-git-proxy を設定したランナーでセッションの開始に失敗する: ランナーのログで access denied by the git proxy、または /git_proxy/ を含む api.anthropic.com アドレスを示す git エラーを探してください。Anthropic がセッションを処理したかどうかを判断して原因を修正するには、git プロキシを使用するランナーでセッションの開始に失敗した場合を参照してください。
• 認証を行うエグレスプロキシ経由でセッションがネットワークに到達できない: --proxy-authorization-command または --proxy-authorization-file で設定したソースが失敗する、30 秒後にタイムアウトする、または空の値を返す場合、ランナーはその接続に 502 Bad Gateway で応答し、理由をログに記録します。ランナーはそのログ内でコマンドの stderr を秘匿し、ヘッダー値をログに記録することはありません。--proxy-authorization-command を使用している場合は、ホスト上でそのコマンドを自分で実行し、ヘッダー値全体が stdout に出力されることを確認してください。代わりにランナーが起動時に could not start the proxy-authorization listener で終了する場合、ランナーはループバックリスナーを開けませんでした。
• ランナーが rejecting the malformed poll response を含む Poll failed 行をログに記録する: ランナーが受け取ったワークポーリングのレスポンスのボディが、キューが想定する JSON ではありません。原因の 1 つは、インターセプトプロキシやキャプティブポータルが独自のページで応答したことです。ランナーがプロキシ経由で接続している場合は、api.anthropic.com からのレスポンスを変更せずに通過させるようにプロキシを設定してください。 ランナーはその不正なレスポンスを拒否し、claude_code_self_hosted_runner_poll_errors_total メトリクスの transport 種別としてカウントし、セッションのライフサイクルで説明されているポーリング失敗時のスケジュールで再試行します。ランナーは稼働中のセッションの処理を続けます。v2.1.246 より前は、ランナーはこのようなレスポンスを空のワークキューとして読み取っていたため、稼働中のセッションが終了したり、ランナーが終了したりすることがありました。
• セッションが no longer exists on the remote または couldn't find remote ref で失敗する: ランナーは git の couldn't find remote ref を、ブランチが削除されたものとして解釈します。ブランチはまだ存在している可能性があります。メッセージ内の名前そのままで git ホスト上のブランチを探し、当てはまる各原因を確認してください:
  • ブランチが存在しない: メッセージの求めに従ってブランチを復元してください。
  • ブランチは存在し、自分はランナーを管理していない: ランナーの管理者にメッセージ全文を送り、ブランチが存在することを伝えてください。
  • ブランチは存在し、ランナーに checkout フックがある: フック内の git コマンドが、フックが 0 以外で終了する前に couldn't find remote ref を stderr に出力することがあります。そのコマンドを見つけ、要求している ref またはフェッチ元のリモートを修正してください。ランナーは、セッションが要求したリビジョンを CLAUDE_RUNNER_REPO_REF としてフックに渡します。
  • ブランチは存在し、ランナーに checkout フックがない: ランナー自身がブランチをフェッチします。リポジトリに --git-host-rewrite が適用される場合は、書き換え先のホストに同じ名前のブランチがあることを確認し、ない場合はそこにブランチをプッシュしてください。
  • ブランチは存在し、ランナーが v2.1.301 より古い: 別の失敗がそれ自体のエラーを表示するように、バージョンを固定するで説明しているとおりランナーをアップグレードしてください。v2.1.301 より前は、エラー出力に couldn't find remote ref を含むその他の失敗も、ブランチの削除として報告されていました。
  ランナーをアップグレードするか原因を修正したら、セッションを再試行するか、新しいセッションを開始してください。これらのチェックで原因が見つからない場合は、問題を報告してください。 セッションが結果をプッシュするソースでは、ブランチが削除されているとセッションが失敗します。セッションが読み取るだけの git ソースでは、ランナーはそのソースをスキップして残りのソースで続行します。スキップするとリポジトリがまったくなくなる場合、ランナーはセッションを失敗させます。v2.1.228 より前は、そのようなセッションは空のディレクトリで開始されていました。
• セッションがリポジトリの 1 つを欠いたまま開始される: checkout フックのないランナーでは、セッションが読み取るだけのリポジトリについて、git ホストがランナーのアクセスチェックを拒否することがあります。その場合、ランナーはそのリポジトリをスキップし、拒否内容を示す [runner:warn] could not access context source 行をログに記録して、残りのリポジトリでセッションを開始します。 ランナーがスキップするのは明確な拒否の場合のみです。つまり、ホストがリポジトリが見つからないと応答した場合、git がホストの認証情報を見つけられない場合、または認証に失敗した場合です。ネットワーク障害、タイムアウト、HTTP 403 の場合は、セッションが結果をプッシュするリポジトリに対する拒否と同様に、引き続きセッションの開始が失敗します。スキップするとリポジトリがまったくなくなるセッションは、引き続きランナーによって失敗とされます。--use-anthropic-git-proxy を使用する場合、ランナーは git プロキシ自体が拒否したリポジトリのみをスキップします。 アクセスチェックはセッションがランナー上で開始されるたびに再度実行されるため、ランナーの git ID に読み取りアクセス権が付与されると、次回の開始時にリポジトリがクローンされます。v2.1.274 より前は、これらの拒否のいずれでもセッションの開始が失敗していました。
• セッションが This runner couldn't read で開始に失敗する: ランナーが git 認証情報を使って git ホストにリポジトリを要求し、見つからないという応答を受け取りました。リポジトリが存在しないか、その認証情報ではリポジトリにアクセスできません。
  • ランナーを管理している場合: ランナーの git 認証情報にリポジトリへの読み取りアクセス権を付与してから、新しいセッションを開始してください。
  • セッションを開始した場合: リポジトリが存在しない場合は、正しいリポジトリで新しいセッションを開始してください。ランナーがリポジトリにアクセスできない場合は、ランナーの管理者にアクセス権の付与を依頼してから、新しいセッションを開始してください。
• セッションの開始または再開に数分かかる: 原因の 1 つは新規のクローンです。各ランナーを空のディスクで起動し、checkout フックがないフリートでは、ランナーは Claude Code を起動する前にセッションのリポジトリを新たにクローンします。空のディスク上で再開するセッションも、同じクローンを再び待つことになります。 新規のクローンを省略するには、事前にウォームアップしたチェックアウトを用意してください。すでに用意している場合は、ランナーがそれを使用していることを確認してください。ランナー自身がクローンを作成し、1 つのセッションの後に終了する場合は、CLAUDE_RUNNER_FETCH_DEPTH をデフォルトの 50 コミットから下げて、フェッチする履歴を減らしてください。 フックを使用している場合、フックはランナーのクローンの代わりに実行されるため、代わりにフックの処理内容を確認してください。開始にかかる時間を確認するには、claude_code_self_hosted_runner_session_init_duration_seconds メトリクスを監視してください。
• ターンが 401 で失敗する: ターンが Anthropic API からの 401 または 403 で終了すると、ランナーは Anthropic から新しい CLAUDE_CODE_OAUTH_TOKEN を取得してセッションに渡します。失敗したターンは再試行されません。このトークンは有効期間が短く、ランナーはセッションの stdin を介してこれをローテーションします。 取得に失敗すると、ランナーはいつ再試行するかを示す inference_token refresh failed 行をログに記録し、セッションが実行されている間は再試行を続けます。 セッション開始から約 30 分後にすべての呼び出しが失敗し始める場合は、ラッパースクリプトがセッションの stdin を切断しているため、トークンのローテーションが届いていない可能性があります。stdin とファイル記述子 3 を接続したままにするを参照してください。 v2.1.274 より前は、ランナーは失敗した取得の再試行を数回で停止し、次の予定された取得を待っていました。失敗したターンでは取得がトリガーされなかったため、次の予定された取得まですべてのターンが 401 で失敗していました。
• claude.ai/code でターンが This model needs a newer version of Claude Code で失敗する: ランナーがセッションの開始に使用する Claude Code のバージョンが、セッションのモデルが必要とするバージョンより古いため、API がリクエストを拒否します。バージョンを固定するで説明しているとおり、メッセージが求めるバージョン以降にランナーをアップグレードしてください。それまでは、セッション内で別のモデルを選択できます。
• ドレイン中に Pod が強制終了される: terminationGracePeriodSeconds を、ランナーが起動時にログに記録する値以上に引き上げてください。シャットダウンのタイミングを参照してください。

​

ランナーが終了したとき

• 正常な終了: ランナーがセッションを終えてドレインした、リタイア時刻に達した、または停止を指示された場合です。環境が再び処理能力を持てるように、ランナーを再起動してください。これらの終了についてはランナーのライフサイクルで説明しています。
• 起動の失敗: ランナーは与えられた設定またはホストでは起動できないため、起動から数秒で終了し、再起動するたびに同じように終了します。より早く再起動しても解決しません。誰かが出力を読み、原因を修正する必要があります。
• 接続の喪失: たとえばホストがスリープしている間など、リースより長く Anthropic に到達できないランナーは、環境から削除されることがあります。削除されたランナーは再接続すると終了します。そのログには、runner record gone server-side を含む [runner:fatal] 行、またはより長い停止の後には poll auth failed が表示されることがあります。ランナーは自動的に再登録されないため、再起動してください。

​

起動の失敗を見分ける

[runner:fatal] --use-anthropic-git-proxy requires --capacity 1 (the proxy URL is per-session and linked worktrees share origin). Omit --use-anthropic-git-proxy or set --capacity 1.

• 行がまったくない: ホストによって強制終了されたランナーは、どちらの行も出力しません。出力が [runner:fatal] 行も error: 行もなく終わっている場合は、たとえばメモリ制限を超えたためにホストまたはオーケストレーターがプロセスを停止したかどうかを確認してください。
• 終了コード: ランナーは、起動のたびに繰り返されるエラー専用の終了コードを用意していません。サポートされていないフラグの組み合わせなどの設定エラーでも、ランナー自身の再試行を通じて API に到達できない状態が続くなど自然に解消する可能性のある失敗でも、同じコードで終了します。待機時間を長くするかどうかは、ランナーがどれだけ早く終了したかに基づいて判断し、理由を知るにはランナーの出力を読んでください。
• 正常に見える環境: --configure-git や Anthropic git プロキシの認証情報のセットアップなど、一部の起動ステップはランナーが環境に登録された後に実行されます。これらのステップのいずれかが失敗すると、プロセスが終了した後も数分間、環境がそのランナーを一覧に表示し続けることがあり、どのランナーも作業をピックアップしていないのに Cloud environments ページに Healthy と表示されることがあります。正常に見える環境でセッションがキューに入ったままになる場合は、スーパーバイザーがランナーを再起動し続けていないか確認してください。

​

待機時間を延ばしながら再起動する

• Kubernetes: このページの Deployment は変更不要です。コンテナが終了した後、kubelet はデフォルトでコンテナを再起動する前に待機し、その待機時間は再起動のたびに上限まで延びます。コンテナが終了せずにしばらく実行されると、待機時間は最初からやり直しになります。 kubelet は、コンテナの実行時間が短かった場合は正常終了の後にも同じ待機を適用します。そのため、頻繁にドレインするランナーも CrashLoopBackOff ステータスを表示することがあるので、ランナーが起動できないと結論づける前に出力を読んでください。以下のコマンドは、Deployment の 1 つの Pod から前回の実行の出力を読み取ります:
  kubectl logs --previous -n claude-runners deploy/claude-runner
  
  前回の実行が起動の失敗であった場合、[runner:fatal] または error: 行は出力の最後のほうの行にあります。別の Pod の前回の実行を読むには、deploy/claude-runner の代わりにその Pod の名前を指定してください。
• Docker と Docker Compose: このページの Compose レシピは変更不要です。restart: always を指定すると、Docker は終了し続けるコンテナの再起動のたびに、上限まで待機時間を長くします。以下のコマンドの <container> をコンテナ名に置き換えてください。このコマンドは、Docker がコンテナを再起動した回数を読み取ります:
  docker inspect --format '{{.RestartCount}}' <container>
  
  コマンドは数値を出力します。数値が増え続けている場合は、Docker がランナーを再起動し続けていることを意味します。
• systemd ユニット: デフォルトでは、systemd は再起動のたびに同じ RestartSec だけ待機し、それを延ばさないため、Restart=always のユニットは、起動できないランナーを毎回同じ間隔で再起動します。起動がユニットの起動レート制限（デフォルトでは 10 秒間に 5 回の起動）に達するほど速く行われると、systemd はユニットの再起動を停止します。ユニットは誰かが再び起動するまで停止したままになります。systemd がそれを許可するのは、レート制限の間隔が経過した後、または systemctl reset-failed の後です。RestartSec はすべての再起動に適用されるため、値を長くすると正常終了後の再起動も遅れます。この 2 つのバランスを取る値を選び、ユニットの再起動回数に対してアラートを設定してください。
• シェルループまたは独自のスーパーバイザー: 同じルールを自分で適用してください。5 秒の待機から始めます。1 分以内に終了した実行の後は、次の再起動までの待機時間を最大 5 分まで 2 倍にします。1 分以上続いた実行の後は、5 秒に戻します。

​

ランナーが終了し続ける理由を確認する

• 最後の [runner:fatal] または error: 行: ランナーが停止した理由が示されています。一般的な原因はトラブルシューティングに記載しています。
• フラグの組み合わせ: Anthropic git プロキシには --capacity 1 が必要です。このページのレシピではより大きな容量を使用しているため、いずれかのレシピにプロキシを追加する場合は容量を下げてください。
• サービスの環境から到達できるもの: ランナーを手動で起動すると成功するのに、スーパーバイザーの下では失敗する場合は、ユーザー、ホームディレクトリ、PATH、メモリ制限を比較してください。--configure-git と Anthropic git プロキシには、PATH 上の git と書き込み可能な ~/.gitconfig が必要です。
• 環境シークレット: シークレットを取り消したか、入力を誤った場合、ランナーは RegisterRunner auth failed を含む行を出力します。
• 環境の Activity タブ: 環境を開き、Activity を選択します。そこに新しいランナーが次々と表示され、どれも作業をピックアップしていない場合は、スーパーバイザーがランナーを再起動しています。

​

セッションはピックアップされたが、Claude が最初のメッセージに応答しない

GET https://api.anthropic.com/v1/code/sessions/<session-id>/worker/events/stream

• レスポンスをバッファリングしない: 到着したとおりに通過させてください。コンテンツタイプは text/event-stream です。
• レスポンスを開いたままにする: レスポンスは最長 1 時間開いたままになることがあります。プロキシにアイドルタイムアウトがある場合は、15 秒よりも十分に長くしてください。Anthropic はデフォルトで少なくともその頻度でキープアライブを送信するためです。

​

ランナーのログで原因を確認する

1. --startup-timeout-min（デフォルトは 15 分）が経過するのを待ちます。するとランナーはセッションを停止し、no child output for を含み — releasing で終わる行をログに記録します。
2. ランナーのログで SDKStartup: SSE を検索します。これらの行は、手順 1 の行から数行後にある finished: interrupted 行に続きます。ほとんどの行にはタイムスタンプがないため、ログコレクターでは別の場所に表示されることがあります。
3. 次の表で該当する行を見つけます:

​

セッションの再試行を止める

​

次のステップ

• セッションをカスタマイズする：ラッパースクリプト、ライフサイクルフック、オンデマンドランナー、MCP サーバー、権限
• エンドツーエンドをテストする：本番環境に昇格させる前に新しいランナーイメージを検証する
• リファレンス：すべての CLI フラグ、環境変数、メトリクス