cc_server CLI

Jedes Prozess-Flag lässt sich als CLI-Flag oder als Umgebungsvariable setzen; das Flag gewinnt, dann die Umgebung, dann die Vorgabe. Zugangsdaten Dritter sind die Ausnahme — siehe unten.

Unbekannte Flags werden stillschweigend ignoriert

Der Argument-Parser ist von Hand geschrieben und überspringt alles, was er nicht erkennt. Ein Tippfehler (--tls-key-file, --bindany) erzeugt also keinen Fehler, und der Server startet einfach mit der Vorgabe. Sieh in die Zeilen des Startlogs, wenn ein Flag keine Wirkung zu haben scheint.

Kern

Flag	Umgebung	Vorgabe	Bedeutung
--data-dir	CC_SERVER_DATA_DIR	das anwendungsbezogene Datenverzeichnis des Betriebssystems je Benutzer (siehe unten)	Datenbanken, Geheimnisse, Modelle und zwischengespeicherte Medien
--port	CC_SERVER_PORT	9030	TCP-Port (0 = ephemer)
--bind	CC_SERVER_BIND	loopback	loopback, oder any/all/0.0.0.0 für jede Schnittstelle (braucht TLS oder --insecure)
--repo-roots	CC_SERVER_REPO_ROOTS	das Home-Verzeichnis des Server-Benutzers	Kommagetrennte Basisverzeichnisse, die ein Client beim Registrieren eines Repos durchsuchen darf. Über eine Wurzel hinaus wird das Durchsuchen abgelehnt
--log-level	CC_SERVER_LOG_LEVEL	warning	debug, info, warning oder error. Die Zeilen zum Hochfahren und zur Bereitschaft werden immer ausgegeben
--server-name	CC_SERVER_NAME	der Hostname der Maschine	Name in Auswahlfeldern, bei der Erkennung und auf den Kopplungsoberflächen

Erreichbarkeit und TLS

Flag	Umgebung	Vorgabe	Bedeutung
--tls-cert	CC_SERVER_TLS_CERT	nicht gesetzt	PEM-Zertifikatskette. Liefert wss:// im Prozess, wenn sie zusammen mit dem Schlüssel gesetzt ist
--tls-key	CC_SERVER_TLS_KEY	nicht gesetzt	Privater PEM-Schlüssel passend zum Zertifikat
--insecure	CC_SERVER_INSECURE	aus	Erlaubt ein Klartext-Bind außerhalb von Loopback. Nur hinter einem TLS-terminierenden Proxy in einem vertrauenswürdigen Netz; wird ignoriert, wenn TLS konfiguriert ist
--public-url	CC_SERVER_PUBLIC_URL	aus dem Bind abgeleitet	Die RPC-URL, die dieser Server gekoppelten Clients bekannt gibt. Setze sie hinter einem Proxy, NAT oder Tunnel ausdrücklich — die Vorgabe ist nur eine Schätzung des lokalen Binds
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	Kommagetrennte Browser-Origins, die /rpc ursprungsübergreifend anwählen dürfen. Loopback und native Clients sind immer erlaubt
--web-client-url	CC_SERVER_WEB_CLIENT_URL	nicht gesetzt	Origin des gehosteten Web-Clients, zu dem die Callbacks für Single Sign-on zurückkehren
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	Der Relay-Broker, dem dieser Server beitritt, damit ein Telefon ihn ohne direkten Weg erreicht
--mdns	CC_SERVER_MDNS	auto	Bekanntmachung im LAN: auto (nur bei einem Bind über Loopback hinaus), on, off. Die Erkennung meldet nur die Existenz — beitreten braucht weiterhin eine Kopplung
--tunnel	CC_SERVER_TUNNEL	off	Verwalteter Tunnel-Anbieter: off, cloudflared, ngrok, tailscale. Öffentliche Erreichbarkeit ist Opt-in
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	aus PATH aufgelöst	Ausdrücklicher Pfad zur Tunnel-Binärdatei
--tunnel-sha256	CC_SERVER_TUNNEL_SHA256	nicht gesetzt	Erwarteter SHA-256 dieser Binärdatei, vor jedem Start geprüft
--tunnel-args	CC_SERVER_TUNNEL_ARGS	leer	Kommagetrennte zusätzliche Argumente für den Tunnel-Aufruf

Indexierung und Zugangsdaten Dritter

Flag	Umgebung	Vorgabe	Bedeutung
--sandbox	CC_SERVER_SANDBOX	on	Ob Agentenläufe in die betriebssystemeigene Sandbox des Hosts gehüllt werden, wenn eine verfügbar ist. Ein Opt-out, kein Einschalten — siehe unten
--code-index	CC_SERVER_CODE_INDEX	on	Notausschalter im Feld für die Code-Graph-Indexierung im Hintergrund. off startet sauber, ohne einen Rebuild
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	Sekunden, die der erste Indexdurchlauf nach dem Bereitschaftsbanner wartet (begrenzt auf 0–300)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	Ob Harness-Läufe eine kleine residente Tool-Menge plus einen Namensindex schicken und den Rest beim ersten Gebrauch laden. Siehe unten
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	Sekunden, die ein Lauf geparkt wartet, bis ein Mensch Zugangsdaten richtet, die ihn nicht bedienen können (begrenzt auf 0–3600). Siehe unten

Ein leerer Wert für Zugangsdaten gilt als nicht gesetzt, der eingebaute Fallback greift also weiter. Ein Build aus dem Quellcode bringt überhaupt keine eingebauten Zugangsdaten mit.

Google Calendar und die GIF-Auswahl von Klipy gibt es nur über die Umgebung — ein Flag --google-client-id / --klipy-app-key gibt es nicht (unbekannte Flags werden ignoriert). Setze GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET und KLIPY_APP_KEY in der Umgebung (oder in einer .env neben dem Server). Leer schaltet die Funktion ab, statt den Start scheitern zu lassen.

--sandbox

Der Server sondiert den Host einmal beim Start und hüllt die Befehlsausführung der Agenten in die betriebssystemeigene Sandbox, sobald ein Backend verfügbar ist: sandbox-exec (Seatbelt) unter macOS, bwrap plus socat unter Linux und WSL2. Wo keins vorhanden ist — unter Windows oder auf einem Linux-Host ohne diese Werkzeuge — fallen die Läufe auf die Bereinigung der Umgebung, die Befehlsrichtlinie und die Aktions-Schutzregeln zurück, und das Startlog sagt, welcher Zustand gilt.

--sandbox off ist der Notausschalter im Feld für den Fall, den die Sonde nicht sieht: einen Host, auf dem das Sandbox-Profil selbst sich falsch verhält. Ein Rebuild ist nicht nötig, und der Server schreibt für die Lebensdauer des Prozesses eine Warnung, damit der Zustand nie still bleibt.

--tool-deferral

Läufe des eingebauten Harness schicken eine kleine residente Menge von Tool-Definitionen plus einen reinen Namensindex des Rests; die Schemas laden beim ersten Gebrauch. Das kürzt den Tool-Block um etwa 78 % und hält die immer sichtbare Menge in dem Band, in dem Modelle Tools zuverlässig wählen. Zurückgestellte Tools bleiben durchgehend über den Namen aufrufbar, und search_tools findet sie nach der Absicht. Siehe Tool-Kontext und Prompt-Caching.

--tool-deferral off macht jedes zugelassene Tool wieder resident und erzeugt die Anfragen, die der Server stellte, bevor es die Zurückstellung gab. Es ist der Notausschalter für ein Modell, das mit der zweistufigen Oberfläche schlecht umgeht — ein Flag statt eines Rebuilds. Es betrifft nur den eingebauten Harness; das tools/list, das externe MCP-Clients sehen, ist immer der vollständige Katalog.

--credential-gate

Ein Lauf, dessen Anbieter-Zugangsdaten fehlen oder aufgebraucht sind, wird geparkt, statt zu scheitern: du bekommst eine Aufforderung, sie zu richten, und der Lauf geht weiter, wenn du das tust. Die Vorgabefrist beträgt 900 Sekunden (15 Minuten) und ist auf 0–3600 begrenzt.

Die Frist ist absichtlich viel länger als die der Freigabeaufforderung: eine Freigabe ist eine Entscheidung, die jemand in Sekunden trifft, Zugangsdaten richten heißt dagegen, ein Terminal zu öffnen, sich anzumelden und zurückzukommen. Die Obergrenze sorgt dafür, dass ein unbeaufsichtigter Lauf — ein Pipeline-Schritt, ein Cron-Trigger, ein Webhook — nicht auf jemanden wartet, der schläft. Läuft sie ab, scheitert der Lauf mit der Meldung, mit der er auch sonst gescheitert wäre.

--credential-gate=0 ist der Notausschalter: nichts wird je geparkt, und schlechte Zugangsdaten beenden den Turn genau so wie vor dem Gate.

Unterbefehle

Befehl	Wirkung
cc_server	Führt den Server, bis SIGINT/SIGTERM kommt
cc_server pair	Stellt ein Gerät bereit und gibt seine ID und den Kopplungsschlüssel aus. Gefahrlos auch für ein Datenverzeichnis, das ein Server schon bedient — der laufende Server nimmt das Gerät ohne Neustart auf
cc_server calendar connect --workspace <id>	Verbindet ein Google-Konto über den Device-Code-Flow mit einem Arbeitsbereich und beendet sich
cc_server update	Prüft auf ein neueres eigenständiges Release, lädt es herunter und verifiziert es
cc_server --version	Gibt die Build-Version und den Git-SHA aus — dieselbe Identität, die /healthz und der RPC-Handshake bekannt geben

pair

Flag	Vorgabe	Bedeutung
--device	web-client	Die Geräte-ID. Die Plattform wird daraus abgeleitet, deshalb erzeugt --device desktop eine Desktop-Zeile und --device ios/android eine Telefon-Zeile; alles andere gilt als Web
--label	Plattformname plus der Hostname dieser Maschine	Anzeigename in der Geräteliste
--host	localhost, oder <this-host>, wenn an jede Schnittstelle gebunden	Host, der in die ausgegebene URL kommt. Setze ihn auf die LAN-IP oder den Tunnel-Host, den ein Client wirklich anwählt
--client-url	nicht gesetzt	Origin des gehosteten Web-Clients. Ergänzt einen scannbaren Deep Link und einen QR im Terminal

pair nimmt auch die Kern-Flags --data-dir, --port und --bind: sie wählen das Datenverzeichnis zum Schreiben und formen die ausgegebene Server-URL (ws auf Loopback, wss bei --bind any). Ein erneutes pair für dasselbe --device rotiert seinen Schlüssel und beendet die laufenden Sitzungen dieses Geräts. Hier ausgestellte Zugangsdaten haben kein Ablaufdatum, anders als die 30 Tage einer Kopplung in der App.

Der --client-url-QR ist nicht der Telefon-QR

pair --client-url füllt das Verbindungsformular des Web-Clients (Server-URL, Geräte-ID und Schlüssel im URL-Fragment). Das Telefon koppelt mit einem anderen Payload, ausgestellt im Kopplungsbereich der App — dem vollständigen Verbindungsdeskriptor des Servers plus einem Ablaufdatum. Die beiden sind nicht austauschbar — siehe Ein Gerät koppeln.

update

--apply ersetzt die Installation; es wird abgelehnt, solange auf dem konfigurierten Port noch ein Server antwortet, außer du gibst --force an. --allow-downgrade erlaubt ein älteres Release.

Der Befehl lehnt Installationen, die ihm nicht gehören, rundheraus ab, mit einer Erklärung statt eines Fehlers:

Umgebung	Erkannt an	Was er sagt
Der eingebettete Server des Desktops	CC_EMBEDDED=1 oder CC_BOOTSTRAP_DEVICE_ID	Aktualisiere stattdessen die App — das Installationsprogramm tauscht den ganzen Baum aus
Ein Quell-Checkout über dart run	der Skriptpfad endet auf .dart	Aktualisiere es mit git
Docker	Container-Merkmale	Zieh ein neueres Image

Prozesslebenszyklus

cc_server läuft bis SIGINT / SIGTERM. Eine weitere Umgebungsvariable steuert das, und der Desktop setzt sie, nicht du:

Variable	Wirkung
CC_EXIT_WITH_PARENT=1	Der Server beendet sich, wenn sein Elternprozess das tut, erkannt daran, dass der Elternprozess das Schreibende seiner stdin-Pipe schließt. Der Desktop setzt sie, damit eine abgestürzte App nie einen verwaisten Server hinterlässt, der das Datenverzeichnis hält

Setze sie nur selbst, wenn du cc_server als Kindprozess beaufsichtigst und dieselbe Garantie willst.

Aufbau des Datenverzeichnisses

Das Vorgabe-Datenverzeichnis ist ~/Library/Application Support/control-center unter macOS, %APPDATA%\control-center unter Windows und $XDG_DATA_HOME/control-center (sonst ~/.local/share/control-center) auf den übrigen Systemen. Ein auf das Arbeitsverzeichnis bezogenes .cc_server wird nur genutzt, wenn sich kein Home- oder Anwendungsdatenverzeichnis auflösen lässt.

Pfad	Inhalt
global.db	Die Registrierung der Arbeitsbereiche, die Benutzer, die gekoppelten Geräte, der Newsfeed und die Warteschlange der Flotte
<workspaceId>/workspace.db	Eine Datenbank je Arbeitsbereich — Agenten, Bereiche, Tickets, Gedächtnis, der Code-Graph
<workspaceId>/chat_credentials/	Token der Chatbots, als einfaches JSON, damit sie mit dem Arbeitsbereich mitgehen
secrets.json	Kopplungsschlüssel, die App-Identität des Anbieters, Token je Benutzer und von Google, SSO (0600)
backups/<timestamp>/	Ein Installations-Snapshot — manifest.json, global.db und eine Kopie jedes Arbeitsbereichs
backups/exports/	Exporte einzelner Arbeitsbereiche, <workspaceId>-<timestamp>.db
backups/transfer/	Zwischenlager für Backup-Downloads und -Uploads; aufgeräumt von der Route, die hineinschreibt
models/	Einbettungs-, Diarisierungs- und Sprachmodelle auf dem Gerät
meetings/<meetingId>/	Aufbewahrtes Audio der Besprechungen
rigs/images/	Importierte Festplattenimages der Rigs (die QEMU-Desktop-Oberfläche)
rigs/smolvm/<rigId>/	Laufzeitzustand der MicroVM je Rig (das Broker-Geheimnis, 0600)
rigs/smolvm-packs/	Vorextrahierte Maschinenpakete — der Cache, der wiederholte Rig-Starts schnell macht
rigs/tls/	Die Zertifizierungsstelle der Dev-Domain für HTTPS der Rigs (Schlüssel 0600)
rigs/run/<rigId>/	QEMU-Overlays, Seed-Images und Schlüssel je VM (0600)

Siehe auch

• Einen Headless-Server betreiben — das Einrichtungsrezept, zu dem diese Flags gehören
• Einen Fleet-Worker betreiben — die separate Binärdatei cc_worker, die sich bei diesem Server registriert
• Sichern und wiederherstellen — dieses Verzeichnis an einen sicheren Ort kopieren
• Backup, Export und Import — der Aufbau der Snapshots und jede Backup-Operation
• Mit einem Remote-Server verbinden — einen Client darauf ausrichten
• Bereitstellung und Clients — warum dem Server alles gehört