CLI cc_server

Setiap flag proses diisi lewat flag CLI atau variabel lingkungan; flag menang, lalu variabel lingkungan, lalu nilai bawaan. Kredensial pihak ketiga adalah pengecualiannya — lihat di bawah.

Inti

Flag	Env	Bawaan	Arti
`--data-dir`	`CC_SERVER_DATA_DIR`	direktori data aplikasi per pengguna OS (lihat di bawah)	Basis data, rahasia, model, dan media yang di-cache
`--port`	`CC_SERVER_PORT`	`9030`	Port TCP (`0` = sementara)
`--bind`	`CC_SERVER_BIND`	`loopback`	`loopback`, atau `any`/`all`/`0.0.0.0` untuk semua antarmuka (perlu TLS atau `--insecure`)
`--repo-roots`	`CC_SERVER_REPO_ROOTS`	direktori home pengguna server	Direktori dasar yang dipisahkan koma yang boleh dijelajahi klien saat mendaftarkan repo. Menjelajah di atas sebuah root ditolak
`--log-level`	`CC_SERVER_LOG_LEVEL`	`warning`	`debug`, `info`, `warning`, atau `error`. Baris booting/ready selalu dicetak
`--server-name`	`CC_SERVER_NAME`	hostname mesin	Nama yang ditampilkan di pemilih, penemuan, dan antarmuka pemasangan

Keterjangkauan dan TLS

Flag	Env	Bawaan	Arti
`--tls-cert`	`CC_SERVER_TLS_CERT`	belum disetel	Rantai sertifikat PEM. Menyajikan `wss://` di dalam proses bila disetel bersama kuncinya
`--tls-key`	`CC_SERVER_TLS_KEY`	belum disetel	Kunci privat PEM yang cocok dengan sertifikatnya
`--insecure`	`CC_SERVER_INSECURE`	nonaktif	Izinkan pengikatan non-loopback plaintext. Hanya di balik proxy terminasi TLS pada jaringan tepercaya; diabaikan bila TLS dikonfigurasi
`--public-url`	`CC_SERVER_PUBLIC_URL`	diturunkan dari pengikatan	URL RPC yang diiklankan server ini ke klien yang dipasangkan. Setel ini secara eksplisit di balik proxy, NAT, atau tunnel — nilai bawaannya hanya perkiraan dari pengikatan lokal
`--allowed-origins`	`CC_SERVER_ALLOWED_ORIGINS`	`https://app.usectrl.dev`	Origin peramban yang dipisahkan koma yang diizinkan menghubungi `/rpc` lintas origin. Loopback dan klien native selalu diizinkan
`--web-client-url`	`CC_SERVER_WEB_CLIENT_URL`	belum disetel	Origin klien web yang dihosting, tempat callback single sign-on dipantulkan kembali
`--signaling-url`	`CC_SERVER_SIGNALING_URL`	`wss://signaling.usectrl.dev`	Broker relay yang diikuti server ini agar ponsel dapat menjangkaunya tanpa jalur langsung
`--mdns`	`CC_SERVER_MDNS`	`auto`	Iklan LAN: `auto` (hanya bila diikat di luar loopback), `on`, `off`. Penemuan hanya mengiklankan keberadaan — bergabung tetap memerlukan pemasangan
`--tunnel`	`CC_SERVER_TUNNEL`	`off`	Penyedia tunnel terkelola: `off`, `cloudflared`, `ngrok`, `tailscale`. Eksposur publik bersifat opsional
`--tunnel-binary`	`CC_SERVER_TUNNEL_BINARY`	diselesaikan dari `PATH`	Jalur biner tunnel yang eksplisit
`--tunnel-sha256`	`CC_SERVER_TUNNEL_SHA256`	belum disetel	SHA-256 yang diharapkan dari biner itu, diverifikasi sebelum setiap spawn
`--tunnel-args`	`CC_SERVER_TUNNEL_ARGS`	kosong	Argumen tambahan yang dipisahkan koma untuk pemanggilan tunnel

Pengindeksan dan kredensial pihak ketiga

Flag	Env	Bawaan	Arti
`--sandbox`	`CC_SERVER_SANDBOX`	`on`	Apakah run agen dibungkus dalam sandbox native OS host bila tersedia. Penolakan ikut (opt-out), bukan pengaktifan — lihat di bawah
`--code-index`	`CC_SERVER_CODE_INDEX`	`on`	Sakelar pemutus lapangan untuk pengindeksan graf kode latar belakang. `off` melakukan boot bersih tanpa build ulang
`--code-index-defer`	`CC_SERVER_CODE_INDEX_DEFER`	`15`	Detik untuk menahan penyapuan indeks pertama setelah banner siap (dibatasi 0–300)
`--tool-deferral`	`CC_SERVER_TOOL_DEFERRAL`	`on`	Apakah run harness mengirim kumpulan alat residen yang kecil plus indeks nama, lalu memuat sisanya saat pertama dipakai. Lihat di bawah
`--credential-gate`	`CC_SERVER_CREDENTIAL_GATE`	`900`	Detik sebuah run diparkir menunggu manusia memperbaiki kredensial yang tidak dapat melayaninya (dibatasi 0–3600). Lihat di bawah

Nilai kosong untuk sebuah kredensial dibaca sebagai belum disetel, sehingga fallback bawaan tetap berlaku. Build dari sumber sama sekali tidak membawa kredensial bawaan.

Google Calendar dan pemilih GIF Klipy hanya dapat diatur lewat variabel lingkungan — tidak ada flag --google-client-id / --klipy-app-key (flag yang tidak dikenal diabaikan). Setel GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET, dan KLIPY_APP_KEY, di lingkungan (atau .env di samping server). Nilai kosong menonaktifkan fitur itu alih-alih menggagalkan boot.

`--sandbox`

Server memeriksa host sekali saat boot dan membungkus eksekusi perintah agen dalam sandbox native OS bila backend tersedia: sandbox-exec (Seatbelt) di macOS, bwrap plus socat di Linux dan WSL2. Bila tidak ada — Windows, atau host Linux yang tidak memiliki alat tersebut — run jatuh ke sanitasi lingkungan, kebijakan perintah, dan pagar pengaman tindakan, dan log startup menyebutkan keadaan mana yang berlaku.

--sandbox off adalah sakelar pemutus lapangan untuk kasus yang tidak dapat dilihat pemeriksaan: host tempat profil sandbox itu sendiri berperilaku salah. Ini tidak memerlukan build ulang dan server mencatat peringatan sepanjang umur proses sehingga keadaan itu tidak pernah senyap.

`--tool-deferral`

Run harness bawaan mengirim kumpulan residen kecil berisi definisi alat plus indeks hanya nama untuk sisanya, yang memuat skemanya saat pertama kali dipakai. Ini memangkas blok alat sekitar 78% dan menjaga kumpulan yang selalu terlihat tetap dalam rentang tempat model memilih alat secara andal. Alat yang ditangguhkan tetap dapat dipanggil dengan namanya sepanjang run, dan search_tools menemukannya berdasarkan maksud. Lihat Konteks alat dan cache prompt.

--tool-deferral off membuat setiap alat yang diizinkan kembali residen, mereproduksi permintaan yang dibuat server sebelum penangguhan ada. Ini sakelar pemutus untuk model yang buruk dalam menangani permukaan dua tingkat — sebuah flag, bukan build ulang. Ini hanya memengaruhi harness bawaan; tools/list MCP yang dilihat klien eksternal selalu katalog lengkap.

`--credential-gate`

Run yang kredensial penyedianya hilang atau habis akan diparkir, bukan digagalkan: operator mendapat perintah untuk memperbaikinya, dan run dilanjutkan jika mereka melakukannya. Tenggat bawaannya 900 detik (15 menit), dibatasi 0–3600.

Tenggat ini sengaja jauh lebih panjang daripada tenggat prompt persetujuan: persetujuan adalah keputusan yang dibuat seseorang dalam hitungan detik, sedangkan memperbaiki kredensial berarti membuka terminal, masuk, lalu kembali. Batas atas itulah yang mencegah run tanpa pengawasan — langkah pipeline, pemicu cron, webhook — menunggu seseorang yang sedang tidur. Saat tenggatnya habis, run gagal dengan pesan yang sama seperti jika digagalkan sejak awal.

--credential-gate=0 adalah sakelar pemutusnya: tidak ada yang pernah diparkir dan kredensial buruk mengakhiri giliran persis seperti sebelum gerbang ini ada.

Subperintah

Perintah	Yang dilakukannya
`cc_server`	Menjalankan server hingga `SIGINT`/`SIGTERM`
`cc_server pair`	Menyediakan perangkat dan mencetak id serta kunci pairing-nya. Aman terhadap direktori data yang sudah disajikan server — server yang berjalan akan mengenali perangkat itu tanpa perlu dimulai ulang
`cc_server calendar connect --workspace <id>`	Menghubungkan akun Google ke ruang kerja melalui alur kode perangkat, lalu keluar
`cc_server update`	Memeriksa, mengunduh, dan memverifikasi rilis mandiri yang lebih baru
`cc_server --version`	Mencetak versi build dan SHA git — identitas yang sama yang diiklankan `/healthz` dan handshake RPC

`pair`

Flag	Bawaan	Arti
`--device`	`web-client`	Id perangkat. Platform disimpulkan darinya, jadi `--device desktop` membuat baris desktop dan `--device ios`/`android` membuat baris ponsel; selain itu diperlakukan sebagai web
`--label`	nama platform plus hostname mesin ini	Nama tampilan di daftar perangkat
`--host`	`localhost`, atau `<this-host>` bila diikat ke semua antarmuka	Host yang disematkan di URL yang dicetak. Setel ke IP LAN atau host tunnel yang benar-benar akan dihubungi klien
`--client-url`	belum disetel	Origin klien web yang dihosting. Menambahkan deep link yang dapat dipindai dan QR terminal

pair juga menerima flag inti --data-dir, --port, dan --bind: flag itu memilih direktori data yang akan ditulis dan membentuk URL server yang dicetak (ws di loopback, wss bila --bind any). Menjalankan ulang pair untuk --device yang sama memutar kuncinya dan memutus sesi aktif perangkat itu. Kredensial yang dibuat di sini tidak memiliki masa kedaluwarsa, berbeda dari 30 hari yang ditetapkan pemasangan di dalam aplikasi.

`update`

--apply menggantikan instalasi; ini ditolak selama server masih menjawab di port yang dikonfigurasi kecuali Anda memberikan --force. --allow-downgrade mengizinkan rilis yang lebih lama.

Perintah ini menolak secara langsung, dengan penjelasan alih-alih galat, untuk instalasi yang bukan miliknya:

Lingkungan	Terdeteksi oleh	Yang dikatakannya
Server tertanam di desktop	`CC_EMBEDDED=1` atau `CC_BOOTSTRAP_DEVICE_ID`	Perbarui aplikasinya sebagai gantinya — penginstal menukar seluruh pohon
Checkout sumber `dart run`	jalur skrip berakhiran `.dart`	Perbarui dengan git
Docker	penanda kontainer	Tarik image yang lebih baru

Siklus hidup proses

cc_server berjalan hingga SIGINT / SIGTERM. Satu variabel lingkungan tambahan mengaturnya, dan variabel itu disetel oleh desktop, bukan oleh Anda:

Variabel	Efek
`CC_EXIT_WITH_PARENT=1`	Server keluar saat proses induknya keluar, dideteksi dari induk yang menutup ujung tulis pipa stdin-nya. Desktop menyetelnya agar aplikasi yang mogok tidak pernah meninggalkan server yatim yang memegang direktori data

Setel sendiri hanya jika Anda mengawasi cc_server sebagai proses anak dan menginginkan jaminan yang sama.

Tata letak direktori data

Direktori data bawaannya adalah ~/Library/Application Support/control-center di macOS, %APPDATA%\control-center di Windows, dan $XDG_DATA_HOME/control-center (atau ~/.local/share/control-center) di tempat lain. .cc_server yang relatif terhadap cwd hanya digunakan bila tidak ada direktori home atau direktori data aplikasi yang dapat ditentukan.

Jalur	Isi
`global.db`	Registri ruang kerja, pengguna, perangkat yang dipasangkan, umpan berita, dan antrean fleet
`<workspaceId>/workspace.db`	Satu basis data per ruang kerja — agen, space, tiket, memori, graf kode
`<workspaceId>/chat_credentials/`	Token bot chat, sebagai JSON biasa, sehingga ikut bersama ruang kerja
`secrets.json`	Kunci pairing, identitas aplikasi penyedia, token per pengguna dan Google, SSO (`0600`)
`backups/<timestamp>/`	Satu snapshot instalasi — `manifest.json`, `global.db`, dan salinan setiap ruang kerja
`backups/exports/`	Ekspor satu ruang kerja, `<workspaceId>-<timestamp>.db`
`backups/transfer/`	Area penampungan untuk unduhan dan unggahan cadangan; dibersihkan oleh rute yang menulisnya
`models/`	Model embedding, diarisasi, dan ucapan di perangkat
`meetings/<meetingId>/`	Audio rapat yang disimpan
`rigs/images/`	Image disk rig yang diimpor (permukaan desktop QEMU)
`rigs/smolvm/<rigId>/`	Status runtime microVM per rig (rahasia broker, `0600`)
`rigs/smolvm-packs/`	Paket mesin yang telah diekstrak — cache yang mempercepat boot rig berulang
`rigs/tls/`	Otoritas sertifikat domain dev untuk HTTPS rig (kunci `0600`)
`rigs/run/<rigId>/`	Overlay QEMU, image seed, dan kunci per VM (`0600`)

Lihat juga

Jalankan server headless — resep penyiapan tempat flag ini menjadi bagiannya
Jalankan pekerja fleet — biner cc_worker terpisah yang mendaftar ke server ini
Cadangkan dan pulihkan — menyalin direktori ini ke tempat yang aman
Cadangan, ekspor, dan impor — tata letak snapshot dan setiap operasi pencadangan
Hubungkan ke server jarak jauh — mengarahkan klien ke sana
Deployment dan klien — mengapa server memiliki semuanya