cc_server CLI

Elke procesflag heeft een CLI-flag of een omgevingsvariabele; de flag wint, dan de omgeving, dan de standaardwaarde. Inloggegevens van derden zijn de uitzondering — zie hieronder.

Onbekende flags worden stil genegeerd

De argumentparser is handmatig geschreven en slaat alles over wat hij niet herkent, dus een typefout (--tls-key-file, --bindany) geeft geen fout — de server start gewoon met de standaardwaarde. Controleer de logregels bij het opstarten wanneer een flag geen effect lijkt te hebben.

Kern

Flag	Env	Standaard	Betekenis
--data-dir	CC_SERVER_DATA_DIR	de app-gegevensmap per gebruiker van het OS (zie hieronder)	Databases, secrets, modellen en gecachte media
--port	CC_SERVER_PORT	9030	TCP-poort (0 = kortstondig)
--bind	CC_SERVER_BIND	loopback	loopback, of any/all/0.0.0.0 voor elke interface (vereist TLS of --insecure)
--repo-roots	CC_SERVER_REPO_ROOTS	de homedirectory van de servergebruiker	Door komma’s gescheiden basismappen die een client mag doorbladeren bij het registreren van een repo. Boven een root bladeren wordt geweigerd
--log-level	CC_SERVER_LOG_LEVEL	warning	debug, info, warning of error. De regels bij het opstarten en bij gereedheid worden altijd afgedrukt
--server-name	CC_SERVER_NAME	de hostnaam van de machine	Naam die wordt getoond in kiezers, discovery en koppelingsoppervlakken

Bereikbaarheid en TLS

Flag	Env	Standaard	Betekenis
--tls-cert	CC_SERVER_TLS_CERT	niet ingesteld	PEM-certificaatketen. Serveert in-process wss:// wanneer hij samen met de sleutel is ingesteld
--tls-key	CC_SERVER_TLS_KEY	niet ingesteld	PEM-privésleutel die bij het certificaat hoort
--insecure	CC_SERVER_INSECURE	uit	Sta een niet-loopbackbind in platte tekst toe. Alleen achter een TLS-beëindigende proxy op een vertrouwd netwerk; genegeerd wanneer TLS is geconfigureerd
--public-url	CC_SERVER_PUBLIC_URL	afgeleid van de bind	De RPC-URL die deze server aan gekoppelde clients adverteert. Stel deze expliciet in achter een proxy, NAT of tunnel — de standaardwaarde is slechts een gok op basis van de lokale bind
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	Door komma’s gescheiden browser-origins die cross-origin /rpc mogen benaderen. Loopback en native clients zijn altijd toegestaan
--web-client-url	CC_SERVER_WEB_CLIENT_URL	niet ingesteld	Origin van de gehoste webclient waar callbacks voor eenmalige aanmelding naartoe terugkeren
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	De relaybroker waar deze server zich bij aansluit, zodat een telefoon hem kan bereiken zonder direct pad
--mdns	CC_SERVER_MDNS	auto	LAN-advertentie: auto (alleen bij een bind buiten loopback), on, off. Discovery adverteert alleen bestaan — koppelen blijft nodig
--tunnel	CC_SERVER_TUNNEL	off	Aanbieder van beheerde tunnels: off, cloudflared, ngrok, tailscale. Openbare blootstelling is opt-in
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	opgelost via PATH	Expliciet pad naar de tunnelbinary
--tunnel-sha256	CC_SERVER_TUNNEL_SHA256	niet ingesteld	Verwachte SHA-256 van die binary, vóór elke spawn geverifieerd
--tunnel-args	CC_SERVER_TUNNEL_ARGS	leeg	Door komma’s gescheiden extra argumenten voor de tunnel-aanroep

Indexering en inloggegevens van derden

Flag	Env	Standaard	Betekenis
--sandbox	CC_SERVER_SANDBOX	on	Of agent-runs worden verpakt in de OS-native sandbox van de host wanneer die beschikbaar is. Een opt-out, geen opt-in — zie hieronder
--code-index	CC_SERVER_CODE_INDEX	on	Noodschakelaar in het veld voor het op de achtergrond indexeren van de codegraph. Met off start hij schoon, zonder herbouw
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	Seconden waarmee de eerste indexeringsronde na de gereedheidsbanner wordt uitgesteld (begrensd op 0–300)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	Of harness-runs een kleine residente toolset plus een naamindex meesturen en de rest bij het eerste gebruik laden. Zie hieronder
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	Seconden dat een run wacht tot een mens een inloggegeven herstelt dat hem niet kan bedienen (begrensd op 0–3600). Zie hieronder

Een lege waarde voor een inloggegeven geldt als niet ingesteld, dus de ingebouwde fallback blijft van toepassing. Een build uit de source bevat helemaal geen ingebouwde inloggegevens.

Google Calendar en de Klipy GIF-kiezer zijn alleen via de omgeving te configureren — er is geen --google-client-id / --klipy-app-key-flag (onbekende flags worden genegeerd). Stel GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET en KLIPY_APP_KEY in de omgeving in (of in een .env naast de server). Leeg schakelt die functie uit in plaats van de boot te laten mislukken.

--sandbox

De server peilt de host één keer bij het opstarten en verpakt de uitvoering van agentcommando’s in de OS-native sandbox wanneer er een backend beschikbaar is: sandbox-exec (Seatbelt) op macOS, bwrap plus socat op Linux en WSL2. Waar die er niet is — Windows, of een Linux-host zonder die tools — vallen runs terug op het saneren van de omgeving, het commandobeleid en de actiebeveiligingen, en geeft het opstartlog aan welke toestand geldt.

--sandbox off is de noodschakelaar in het veld voor het geval dat de peiling niet kan zien: een host waar het sandboxprofiel zelf zich misdraagt. Het vraagt geen herbouw, en de server logt een waarschuwing zolang het proces leeft, zodat de toestand nooit stil blijft.

--tool-deferral

Runs van de ingebouwde harness sturen een kleine residente set tooldefinities plus een naamindex van de rest mee; die laatste laden hun schema’s de eerste keer dat ze worden gebruikt. Dat verkleint het toolblok met ongeveer 78% en houdt de altijd zichtbare set binnen het bereik waarin modellen tools betrouwbaar kiezen. Uitgestelde tools blijven de hele tijd op naam aanroepbaar, en search_tools vindt ze op intentie. Zie Toolcontext en promptcaching.

--tool-deferral off maakt elke toegelaten tool weer resident en reproduceert de verzoeken die de server deed voordat uitstelling bestond. Het is de noodschakelaar voor een model dat slecht overweg kan met het oppervlak met twee niveaus — een flag in plaats van een herbouw. Het beïnvloedt alleen de ingebouwde harness; de MCP-tools/list die externe clients zien, is altijd de volledige catalogus.

--credential-gate

Een run waarvan het provider-inloggegeven ontbreekt of op is, wordt geparkeerd in plaats van mislukt: de beheerder krijgt een prompt om het te herstellen, en de run gaat verder als dat gebeurt. De standaarddeadline is 900 seconden (15 minuten), begrensd op 0–3600.

De deadline is bewust veel ruimer dan die van de goedkeuringsprompt: een goedkeuring is een beslissing die iemand in seconden neemt, terwijl het herstellen van een inloggegeven betekent dat je een terminal opent, inlogt en terugkomt. Dat plafond weerhoudt een onbeheerde run — een pipelinestap, een cron-trigger, een webhook — ervan te wachten op iemand die ligt te slapen. Wanneer hij verstrijkt, mislukt de run met de melding waarmee hij toch al zou zijn mislukt.

--credential-gate=0 is de noodschakelaar: er wordt nooit iets geparkeerd en een slecht inloggegeven beëindigt de beurt precies zoals voordat de gate bestond.

Subcommando’s

Commando	Wat het doet
cc_server	Draait de server tot SIGINT/SIGTERM
cc_server pair	Provisioneert een apparaat en drukt het id en de koppelingssleutel af. Veilig tegen een datadirectory die een server al bedient — de draaiende server neemt het apparaat over zonder herstart
cc_server calendar connect --workspace <id>	Verbindt een Google-account via de devicecode-flow met een werkruimte en sluit daarna af
cc_server update	Controleert op, downloadt en verifieert een nieuwere standalone release
cc_server --version	Drukt de buildversie en git-SHA af — dezelfde identiteit die /healthz en de RPC-handshake adverteren

pair

Flag	Standaard	Betekenis
--device	web-client	Het apparaat-id. Het platform wordt eruit afgeleid, dus --device desktop maakt een desktoprij aan en --device ios/android een telefoonrij; al het andere wordt als web behandeld
--label	platformnaam plus de hostnaam van deze machine	Weergavenaam in de apparatenlijst
--host	localhost, of <this-host> bij een bind op elke interface	Host om in de afgedrukte URL op te nemen. Stel hem in op het LAN-IP of tunnelhost dat een client daadwerkelijk aanspreekt
--client-url	niet ingesteld	Origin van de gehoste webclient. Voegt een scanbare deeplink en terminal-QR toe

pair accepteert ook de kern-flags --data-dir, --port en --bind: die kiezen de datadirectory waarin wordt geschreven en bepalen de afgedrukte server-URL (ws op loopback, wss bij --bind any). Als je pair opnieuw uitvoert voor hetzelfde --device, roteert de sleutel en vervallen de live-sessies van dat apparaat. Een referentie die je hier aanmaakt, heeft geen vervaldatum, anders dan de 30 dagen die een koppeling in de app instelt.

De QR van --client-url is niet de telefoon-QR

pair --client-url vult het verbindingsformulier van de webclient in (server-URL, apparaat-id en sleutel in het URL-fragment). De telefoon koppelt met een andere payload, aangemaakt vanuit het koppelingspaneel in de app — de volledige verbindingsdescriptor van de server plus een vervaldatum. De twee zijn niet uitwisselbaar — zie Een apparaat koppelen.

update

--apply vervangt de installatie; het wordt geweigerd zolang er nog een server antwoordt op de geconfigureerde poort, tenzij je --force meegeeft. Met --allow-downgrade mag je terug naar een oudere release.

Het commando weigert botweg, met een uitleg in plaats van een fout, voor installaties die het niet bezit:

Omgeving	Herkend aan	Wat er staat
De ingebouwde server van de desktop	CC_EMBEDDED=1 of CC_BOOTSTRAP_DEVICE_ID	Werk in plaats daarvan de app bij — de installer vervangt de hele boom
Een source-checkout met dart run	het scriptpad eindigt op .dart	Werk hem bij met git
Docker	containermarkers	Haal een nieuwere image op

Proceslevenscyclus

cc_server draait tot SIGINT / SIGTERM. Eén extra omgevingsvariabele bepaalt dat, en die wordt door de desktop ingesteld, niet door jou:

Variabele	Effect
CC_EXIT_WITH_PARENT=1	De server stopt wanneer zijn bovenliggende proces stopt, gedetecteerd doordat het bovenliggende proces het schrijfuiteinde van zijn stdin-pipe sluit. De desktop stelt dit in zodat een gecrashte app nooit een verweesde server achterlaat die de datadirectory vasthoudt

Stel hem alleen zelf in als je cc_server als kindproces aanstuurt en dezelfde garantie wilt.

Indeling van de datadirectory

De standaard datadirectory is ~/Library/Application Support/control-center op macOS, %APPDATA%\control-center op Windows en $XDG_DATA_HOME/control-center (anders ~/.local/share/control-center) elders. Een .cc_server relatief aan de cwd wordt alleen gebruikt als er geen home- of app-gegevensmap kan worden bepaald.

Pad	Inhoud
global.db	Het werkruimteregister, gebruikers, gekoppelde apparaten, de nieuwsfeed en de fleetwachtrij
<workspaceId>/workspace.db	Eén database per werkruimte — agenten, ruimtes, tickets, geheugen, de codegraph
<workspaceId>/chat_credentials/	Tokens van de chatbot, als platte JSON, zodat ze met de werkruimte meegaan
secrets.json	Koppelingssleutels, de app-identiteit van de provider, tokens per gebruiker en Google-tokens, SSO (0600)
backups/<timestamp>/	Eén momentopname van de installatie — manifest.json, global.db en een kopie van elke werkruimte
backups/exports/	Exportbestanden van één werkruimte, <workspaceId>-<timestamp>.db
backups/transfer/	Staging voor het downloaden en uploaden van back-ups; opgeruimd door de route die erin schrijft
models/	Embedding-, diarisatie- en spraakmodellen op het apparaat
meetings/<meetingId>/	Bewaarde vergaderaudio
rigs/images/	Geïmporteerde rig-schijfimages (het QEMU-desktopoppervlak)
rigs/smolvm/<rigId>/	Runtime-status per rig-microVM (het brokersecret, 0600)
rigs/smolvm-packs/	Vooraf uitgepakte machinepakketten — de cache die herhaalde rig-boots snel maakt
rigs/tls/	De certificaatautoriteit van het dev-domein voor HTTPS van rigs (sleutels 0600)
rigs/run/<rigId>/	QEMU-overlays, seed-images en sleutels per VM (0600)

Zie ook

• Een headless server draaien — het installatierecept waar deze flags bij horen
• Een fleet-worker draaien — de aparte cc_worker-binary die zich bij deze server registreert
• Back-uppen en herstellen — deze map op een veilige plek kopiëren
• Backup, export en import — de opbouw van momentopnamen en elke back-upbewerking
• Verbinden met een externe server — een client erop richten
• Deployment en clients — waarom de server alles bezit