Jalankan pekerja fleet

Jalankan cc_worker di mesin cadangan untuk menambah kapasitas eksekusi fleet Anda. Ini adalah binary pure-Dart — tanpa engine Flutter — yang dipasangkan dengan cc_server, mendeklarasikan kapabilitas host, mengirim heartbeat, menarik pekerjaan sewaan, mengeksekusinya, dan mengalirkan peristiwa proses kembali. Worker ini tidak menyimpan state permanen: supervisor akan memulainya ulang dan worker mendaftar kembali.

Anda perlu cc_server yang sudah berjalan terlebih dahulu — lihat Jalankan server headless.

Worker yang telah dipasangkan akan mendaftar, mengirim heartbeat, dan menunggu pekerjaan sewaan. Kirim pekerjaan dengan fleet.submitJob. Pengiriman agen di server ini tidak melewati fleet; sinyal keberhasilan untuk panduan ini adalah munculnya worker di panel fleet dengan heartbeat yang baru. Worker in-process yang terdaftar saat boot memiliki peta runner yang kosong, sehingga pekerjaan yang ditempatkan padanya mengembalikan No local runner for job kind ….

Prasyarat

Dart SDK. Repo ini mematok SDK-nya dengan fvm, jadi awali perintah dengan fvm.
Repositori ini telah di-checkout di mesin worker.
cc_server yang dapat dijangkau (loopback untuk pengembangan, LAN atau jarak jauh untuk produksi).
git di PATH — worker menyiapkan repo dan menjalankan probe git.

Langkah 1: Bangun binary

cd apps/cc_worker
fvm dart build cli

Perintah ini menghasilkan bundel mandiri di ./build/cli/<os_arch>/bundle/bin/cc_worker.

Langkah 2: Terbitkan kredensial worker

cc_server hanya menerima worker yang menyertakan id perangkat yang dipasangkan dan pre-shared key — termasuk server loopback. Terbitkan keduanya di mesin server (pair dapat dijalankan selagi server hidup; perangkat baru akan dikenali tanpa perlu memulai ulang):

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

Perintah ini mencetak Device id dan Pairing key — itulah nilai yang diterima oleh --device-id dan --psk / --psk-file / CC_WORKER_PSK.

Langkah 3: Jalankan worker

Untuk server yang telah dipasangkan:

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

Untuk server loopback (tetap dipasangkan — cc_server selalu menjalankan handshake PSK):

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

Flag	Deskripsi	Default
`--server <url>`	URL `cc_server` (`ws://`/`wss://`; `http(s)` dan jalur `/rpc` yang tidak ada akan dipaksa ke bentuk yang benar). Wajib.	—
`--name <name>`	Nama worker yang tampil untuk operator.	nama host
`--device-id <id>`	Id perangkat yang dipasangkan secara stabil, juga dipakai sebagai id worker.	`cc-worker`
`--psk-file <path>`	Berkas yang baris non-kosong pertamanya berisi pairing key. Lebih diutamakan daripada `--psk`.	—
`--psk <key>`	Pairing key di baris perintah. Terlihat di `ps` dan riwayat shell — binary akan memperingatkan.	—
`--max-jobs <n>`	Batas keras jumlah pekerjaan yang dieksekusi proses ini secara bersamaan (bilangan bulat positif).	`4`

Urutan resolusi kunci adalah --psk-file → CC_WORKER_PSK → --psk. Menghilangkan semua sumber akan melewati handshake autentikasi worker; cc_server sungguhan kemudian menolak sesi (auth_denied) alih-alih menerima worker tanpa autentikasi. Flag yang tidak dikenal merupakan kesalahan penggunaan (exit 64) — tidak seperti cc_server, binary ini memakai package:args dan tidak mengabaikan salah ketik.

CC_WORKER_CACHE menimpa direktori cache materialisasi worktree (default: direktori cc_worker_cache di bawah direktori temp sistem).

Worker mendaftar dengan fleet.registerWorker, lalu mengirim heartbeat setiap 20 detik dan melakukan polling untuk sewa setiap 2 detik. Worker berjalan hingga menerima SIGINT/SIGTERM; letakkan di bawah systemd atau launchd agar ia dimulai ulang dan mendaftar kembali setelah crash atau reboot.

Langkah 4: Verifikasi di panel fleet

Buka Observabilitas di aplikasi desktop atau web, beralihlah ke tab Langsung, dan gulir ke bawah. Pekerja mencantumkan setiap worker yang terdaftar beserta platform, inti, kunci kapabilitas, dan heartbeat terakhirnya; Job mencantumkan pekerjaan yang didistribusikan ke semua worker tersebut.

Munculnya worker Anda di sana dengan heartbeat yang masih baru adalah konfirmasi bahwa pemasangan dan pendaftaran berhasil.

Dari ubin seorang worker, Anda dapat kosongkan worker tersebut (menyelesaikan pekerjaan yang sedang berjalan, tidak mengambil sewa baru), lanjutkan worker yang sedang dikosongkan, cabut kredensialnya, atau hapus barisnya.

Baris worker dan job tersimpan di global.db milik server — worker sendiri tidak menulis apa pun ke disk selain cache materialisasi.

Yang diiklankan worker

Saat pendaftaran, worker mendeteksi kapabilitasnya secara otomatis dan penjadwal mencocokkan pekerjaan dengannya. Anda tidak mengonfigurasi ini secara manual:

OS dan arsitektur (macos/linux/windows, arm64/x64) — probe yang tepat, dengan cadangan ke uname -m / PROCESSOR_ARCHITECTURE
Inti dan RAM — jumlah inti yang tepat; RAM turun menjadi 0 jika tidak dapat diprobe
flutter — disetel saat Flutter SDK dapat dijangkau (flutter polos, lalu fvm flutter); job golden-render memerlukannya
sandbox — native-macos di macOS, native-linux di Linux. Ini adalah petunjuk penempatan, bukan janji: worker mengiklankan backend yang dimiliki platformnya, tetapi tidak membungkus job yang dijalankannya di dalam backend itu. Tidak seperti cc_server, cc_worker menjalankan job sewaan secara langsung
always-on dan parallel — cc_worker khusus selalu mengiklankan keduanya, sehingga layak untuk batch eval dan kapasitas paralel sekali pakai lainnya

Deteksi dilakukan secara best-effort: apa pun yang tidak dapat diprobe akan turun ke default yang aman alih-alih menggagalkan startup.

Apa yang akan dieksekusi worker

Protokol sewa membawa enam jenis job:

Jenis	Apa itu
`agentRun`	Satu kali eksekusi agen (pengiriman)
`pipelineStep`	Eksekusi langkah pipeline
`codeIndex`	Pembangunan indeks kode repo
`goldenRender`	Render golden visual UI (memerlukan `flutter`)
`benchmark`	Jalannya benchmark performa
`evalBatch`	Batch eval (lebih menyukai kapasitas `parallel`)

Eksekusi adalah implementasi streaming subproses yang nyata, bukan runtime agen tertanam yang lengkap. Saat sewa membawa repoRemote, worker menjalankan git clone --depth 1 ke direktori cache yang di-key berdasarkan remote dan SHA, lalu git fetch dan git checkout. Untuk agentRun, worker menjalankan perintah pada CC_JOB_COMMAND milik env sewa di direktori kerja, mengalirkan stdout dan stderr kembali sebagai peristiwa; tanpa CC_JOB_COMMAND, worker menggema prompt agar transport tetap teruji dari ujung ke ujung. Jenis lainnya menjalankan perintah nyata yang kecil (git rev-parse HEAD, git --version) sebagai probe yang jujur. Kredensial berskope job di env sewa disuntikkan ke setiap subproses dan tidak pernah ditulis ke log.

Peristiwa dikelompokkan dan di-flush setiap 250 milidetik atau setiap 32 peristiwa; setiap job berakhir dengan peristiwa done dan laporan penyelesaian. Modelnya adalah heartbeat plus sewa ber-TTL pendek: jika worker kehilangan kontak, sewanya kedaluwarsa dan server mengambil kembali job tersebut untuk dicoba ulang. Tidak ada state permanen di worker dan tidak ada konsensus atau work-stealing antar worker.

Panduan terkait

Konsep terkait

Deployment dan klien