플릿 워커 실행

여유 있는 머신에서 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단계: 플릿 패널에서 확인

데스크톱 또는 웹 앱에서 옵저버빌리티를 열고 실시간 탭으로 전환한 뒤 맨 아래로 스크롤합니다. 워커는 등록된 모든 워커를 플랫폼, 코어, 기능 키, 마지막 하트비트와 함께 나열하고, 작업은 이들에게 분산된 작업을 나열합니다.

워커가 최근 하트비트와 함께 여기에 나타나면 페어링과 등록이 성공한 것입니다.

워커 타일에서 워커를 드레인하거나(현재 작업을 마치고 새 리스를 받지 않음), 드레인 중인 워커를 재개하거나, 자격 증명을 철회하거나, 행을 제거할 수 있습니다.

워커와 작업 행은 서버의 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는 항상 두 가지를 모두 알리므로, 평가 배치와 기타 일회성 병렬 용량의 대상이 될 수 있습니다

감지는 최선 노력 방식입니다. 확인할 수 없는 항목은 시작에 실패하는 대신 안전한 기본값으로 저하됩니다.

워커가 실행하는 작업

리스 프로토콜은 여섯 가지 작업 종류를 전달합니다:

종류	설명
`agentRun`	단일 에이전트 실행(디스패치)
`pipelineStep`	파이프라인 단계 실행
`codeIndex`	저장소 코드 인덱스 빌드
`goldenRender`	UI 시각적 골든 렌더(`flutter` 필요)
`benchmark`	성능 벤치마크 실행
`evalBatch`	평가 배치(`parallel` 용량 선호)

실행은 실제 서브프로세스 스트리밍 구현이며, 완전한 내장 에이전트 런타임이 아닙니다. 리스에 repoRemote가 있으면 워커는 원격과 SHA를 키로 하는 캐시 디렉터리로 git clone --depth 1을 수행한 뒤 git fetch와 git checkout을 실행합니다. agentRun의 경우 리스 환경의 CC_JOB_COMMAND에 있는 명령을 작업 디렉터리에서 실행하고 stdout과 stderr를 이벤트로 스트리밍합니다. CC_JOB_COMMAND가 없으면 프롬프트를 그대로 출력해 전송 경로를 끝까지 점검합니다. 나머지 종류는 작은 실제 명령(git rev-parse HEAD, git --version)을 정직한 프로브로 실행합니다. 리스 환경의 작업 범위 자격 증명은 모든 서브프로세스에 주입되며 로그에는 기록되지 않습니다.

이벤트는 배치로 모아 250ms마다 또는 32개 이벤트마다 플러시되며, 각 작업은 done 이벤트와 완료 보고로 끝납니다. 모델은 하트비트와 짧은 TTL의 리스로 구성됩니다. 워커가 연결을 잃으면 리스가 만료되고 서버가 재시도를 위해 해당 작업을 회수합니다. 워커에는 영구 상태가 없고, 워커 간 합의나 작업 훔치기도 없습니다.