フリートワーカーを実行

予備のマシンで cc_worker を実行すると、フリートに実行キャパシティを追加できます。これは Flutter エンジンを必要としない純粋な Dart バイナリで、cc_server とペアリングし、ホストのケイパビリティを宣言してハートビートを送り、リースされたジョブを取得して実行し、プロセスイベントをストリームで返します。永続状態を一切持たないため、スーパーバイザーが再起動すれば再登録されます。

まず稼働中の cc_server が必要です — ヘッドレスサーバーを実行を参照してください。

ペアリング済みのワーカーは登録し、ハートビートを送り、リースされたジョブを待ちます。作業は fleet.submitJob で投入します。このサーバー上のエージェントディスパッチはフリートを経由しません。このガイドの成功シグナルは、ワーカーが新しいハートビートとともにフリートパネルに表示されることです。起動時に登録されるインプロセスワーカーはランナーマップが空なので、そこに置かれたジョブは No local runner for job kind … を返します。

前提条件

Dart SDK。このリポジトリは fvm で SDK を固定しているため、コマンドの先頭に fvm を付けます。
ワーカーマシンにチェックアウトされたこのリポジトリ。
到達可能な cc_server（開発ならループバック、本番なら LAN またはリモート）。
PATH 上の git — ワーカーはリポジトリを実体化し、git のプローブを実行します。

ステップ 1: バイナリをビルドする

cd apps/cc_worker
fvm dart build cli

これにより、./build/cli/<os_arch>/bundle/bin/cc_worker に自己完結型のバンドルが生成されます。

ステップ 2: ワーカーの資格情報を発行する

cc_server は、ペアリング済みデバイス ID と事前共有キーを提示するワーカーだけを受け入れます — ループバックサーバーも例外ではありません。これらはサーバーマシンで発行します（pair はサーバーの稼働中でも実行でき、新しいデバイスは再起動なしで認識されます）:

cc_server pair --data-dir <dir> --device my-worker --label "Build box"

Device id と Pairing key が出力され、それぞれ --device-id と --psk / --psk-file / CC_WORKER_PSK が受け取る値になります。

ステップ 3: ワーカーを起動する

ペアリング済みサーバーに対して:

./build/cli/<os_arch>/bundle/bin/cc_worker \
  --server wss://host:9030 --device-id my-worker --psk-file /path/to/worker.psk

ループバックサーバーに対して（こちらもペアリングが必要です — cc_server は常に PSK ハンドシェイクを実行します）:

fvm dart run cc_worker --server ws://localhost:9030 \
  --device-id my-worker --psk-file /path/to/worker.psk

フラグ	説明	既定値
`--server <url>`	cc_server URL（`ws://`/`wss://`。`http(s)` と `/rpc` パスの欠落は強制変換されます）。必須。	—
`--name <name>`	オペレーターに表示されるワーカー名。	ホスト名
`--device-id <id>`	安定したペアリング済みデバイス ID。ワーカー ID としても使われます。	`cc-worker`
`--psk-file <path>`	最初の空でない行がペアリングキーであるファイル。`--psk` より優先されます。	—
`--psk <key>`	コマンドライン上のペアリングキー。`ps` とシェル履歴に残るため、バイナリが警告します。	—
`--max-jobs <n>`	このプロセスが同時に実行するジョブの上限（正の整数）。	`4`

キーの解決順序は --psk-file → CC_WORKER_PSK → --psk です。すべての指定を省略するとワーカーの認証ハンドシェイクがスキップされ、その場合、実際の cc_server は未認証のワーカーを受け入れるのではなく、セッションを拒否します（auth_denied）。不明なフラグは使用エラーになります（exit 64）— cc_server と異なり、このバイナリは package:args を使うため、タイプミスを無視しません。

CC_WORKER_CACHE はワークツリーの実体化キャッシュディレクトリを上書きします（既定: システムの一時ディレクトリ配下の cc_worker_cache ディレクトリ）。

ワーカーは fleet.registerWorker で登録し、その後 20 秒ごとにハートビートを送り、2 秒ごとにリースをポーリングします。SIGINT/SIGTERM まで動作し続けるため、クラッシュや再起動の後に自動再起動して再登録されるよう、systemd や launchd の下で実行してください。

ステップ 4: フリートパネルで確認する

デスクトップまたは Web アプリでオブザーバビリティを開き、ライブタブに切り替えて一番下までスクロールします。ワーカーには、登録済みの各ワーカーがプラットフォーム、コア数、ケイパビリティキー、最終ハートビートとともに一覧表示され、ジョブにはそれらに分散されたジョブが一覧表示されます。

そこに自分のワーカーが最近のハートビートとともに表示されていれば、ペアリングと登録が成功した証拠です。

ワーカーのタイルから、そのワーカーをドレイン（実行中のジョブを完了させ、新しいリースを受け取らない）、ドレイン中のワーカーの再開、資格情報の失効、行の削除ができます。

ワーカーとジョブの行はサーバーの global.db にあり、ワーカー自身は実体化キャッシュ以外にディスクへ何も書き込みません。

ワーカーが公開するもの

登録時にワーカーは自身のケイパビリティを自動検出し、スケジューラーはそれに照らしてジョブをマッチングします。これらを手動で設定する必要はありません:

OS とアーキテクチャ（macos/linux/windows、arm64/x64）— 厳密なプローブで、uname -m / PROCESSOR_ARCHITECTURE にフォールバックします
コア数と RAM — 正確なコア数。RAM はプローブできない場合 0 に縮退します
flutter — Flutter SDK に到達できる場合に設定されます（素の flutter、次に fvm flutter）。ゴールデンレンダーのジョブには必須です
sandbox — macOS では native-macos、Linux では native-linux。これは配置のヒントであり、約束ではありません。ワーカーは自分のプラットフォームが_持つ_バックエンドを公開しますが、実行するジョブをそれでラップすることはありません。cc_server と異なり、cc_worker はリースされたジョブを直接起動します
always-on と parallel — 専用の cc_worker は常に両方を公開するため、評価バッチやその他の使い捨ての並列キャパシティの対象になります

検出はベストエフォートです。プローブできないものは、起動を失敗させるのではなく安全な既定値に縮退します。

ワーカーが実行するもの

リースプロトコルは 6 種類のジョブ種別を運びます:

種別	内容
`agentRun`	単一のエージェント実行（ディスパッチ）
`pipelineStep`	パイプラインステップの実行
`codeIndex`	リポジトリのコードインデックス構築
`goldenRender`	UI ビジュアルのゴールデンレンダー（`flutter` が必要）
`benchmark`	パフォーマンスベンチマークの実行
`evalBatch`	評価バッチ（`parallel` キャパシティを優先）

実行は実際のサブプロセスストリーミングの実装であり、完全な組み込みエージェントランタイムではありません。リースが repoRemote を運ぶ場合、ワーカーはリモートと SHA をキーにしたキャッシュディレクトリへ git clone --depth 1 を実行し、続いて git fetch と git checkout を行います。agentRun ではワークディレクトリでリース env の CC_JOB_COMMAND にあるコマンドを実行し、stdout と stderr をイベントとしてストリームで返します。CC_JOB_COMMAND がない場合はプロンプトをエコーするので、トランスポートは引き続きエンドツーエンドで検査されます。他の種別は正直なプローブとして小さな実コマンド（git rev-parse HEAD、git --version）を実行します。リース env 内のジョブスコープの資格情報はすべてのサブプロセスに注入され、ログに書き込まれることはありません。

イベントはバッチ化され、250ms ごと、または 32 イベントごとにフラッシュされます。各ジョブは終了イベントと完了レポートで終わります。モデルはハートビートと短い TTL のリースです。ワーカーが連絡を失うとリースが期限切れになり、サーバーが再試行のためにジョブを回収します。ワーカーに永続状態はなく、ワーカー間のコンセンサスやワークスティーリングもありません。