CLI cc_server

Chaque réglage du processus accepte un drapeau de ligne de commande ou une variable d’environnement ; le drapeau l’emporte, puis la variable d’environnement, puis la valeur par défaut. Les identifiants tiers font exception — voir ci-dessous.

Les drapeaux inconnus sont ignorés en silence

L’analyseur d’arguments est écrit à la main et ignore tout ce qu’il ne reconnaît pas : une faute de frappe (--tls-key-file, --bindany) ne produit donc aucune erreur — le serveur démarre simplement avec la valeur par défaut. Vérifiez les lignes du journal de démarrage lorsqu’un drapeau semble sans effet.

Réglages principaux

Drapeau	Variable	Défaut	Signification
--data-dir	CC_SERVER_DATA_DIR	le répertoire de données applicatives par utilisateur du système d’exploitation (voir ci-dessous)	Bases de données, secrets, modèles et médias mis en cache
--port	CC_SERVER_PORT	9030	Port TCP (0 = éphémère)
--bind	CC_SERVER_BIND	loopback	loopback, ou any/all/0.0.0.0 pour toutes les interfaces (exige TLS ou --insecure)
--repo-roots	CC_SERVER_REPO_ROOTS	le répertoire personnel de l’utilisateur du serveur	Répertoires de base séparés par des virgules dans lesquels un client peut parcourir l’arborescence au moment d’enregistrer un dépôt. Toute navigation au-dessus d’une racine est refusée
--log-level	CC_SERVER_LOG_LEVEL	warning	debug, info, warning ou error. Les lignes de démarrage et de disponibilité s’affichent toujours
--server-name	CC_SERVER_NAME	le nom d’hôte de la machine	Nom affiché dans les sélecteurs, la découverte et les surfaces d’appairage

Joignabilité et TLS

Drapeau	Variable	Défaut	Signification
--tls-cert	CC_SERVER_TLS_CERT	non défini	Chaîne de certificats PEM. Sert wss:// dans le processus lorsqu’elle est définie avec la clé
--tls-key	CC_SERVER_TLS_KEY	non défini	Clé privée PEM correspondant au certificat
--insecure	CC_SERVER_INSECURE	désactivé	Autorise une liaison non locale en clair. Uniquement derrière un proxy qui termine le TLS, sur un réseau de confiance ; ignoré lorsque TLS est configuré
--public-url	CC_SERVER_PUBLIC_URL	dérivée de la liaison	L’URL RPC que ce serveur annonce aux clients appairés. Définissez-la explicitement derrière un proxy, un NAT ou un tunnel — la valeur par défaut ne fait que deviner à partir de la liaison locale
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	Origines de navigateur séparées par des virgules autorisées à joindre /rpc en cross-origin. La boucle locale et les clients natifs sont toujours autorisés
--web-client-url	CC_SERVER_WEB_CLIENT_URL	non défini	Origine du client web hébergé vers lequel rebondissent les rappels de connexion unique
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	Le courtier relais que ce serveur rejoint pour qu’un téléphone puisse l’atteindre sans chemin direct
--mdns	CC_SERVER_MDNS	auto	Annonce sur le réseau local : auto (uniquement en cas de liaison au-delà de la boucle locale), on, off. La découverte n’annonce que l’existence — se connecter exige toujours un appairage
--tunnel	CC_SERVER_TUNNEL	off	Fournisseur de tunnel géré : off, cloudflared, ngrok, tailscale. L’exposition publique se demande explicitement
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	résolu dans le PATH	Chemin explicite du binaire de tunnel
--tunnel-sha256	CC_SERVER_TUNNEL_SHA256	non défini	SHA-256 attendu de ce binaire, vérifié avant chaque lancement
--tunnel-args	CC_SERVER_TUNNEL_ARGS	vide	Arguments supplémentaires séparés par des virgules pour l’invocation du tunnel

Indexation et identifiants tiers

Drapeau	Variable	Défaut	Signification
--sandbox	CC_SERVER_SANDBOX	on	Si les exécutions d’agents sont encapsulées dans le bac à sable natif du système d’exploitation de l’hôte lorsqu’il en existe un. Une désactivation, et non une activation — voir ci-dessous
--code-index	CC_SERVER_CODE_INDEX	on	Interrupteur de coupure en production pour l’indexation en arrière-plan du graphe de code. off démarre proprement, sans reconstruction
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	Secondes pendant lesquelles la première passe d’indexation est retenue après la bannière de disponibilité (bornée à 0–300)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	Si les exécutions du harnais envoient un petit ensemble résident d’outils plus un index de noms, le reste étant chargé à la première utilisation. Voir ci-dessous
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	Secondes pendant lesquelles une exécution est mise en attente qu’un humain corrige un identifiant qui ne peut pas la servir (bornée à 0–3600). Voir ci-dessous

Une valeur vide pour un identifiant équivaut à une absence de définition : le repli intégré s’applique donc toujours. Une compilation à partir du code source ne comporte aucun identifiant intégré.

Google Calendar et le sélecteur de GIF Klipy sont accessibles uniquement par l’environnement — il n’existe aucun drapeau --google-client-id / --klipy-app-key (les drapeaux inconnus sont ignorés). Définissez GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET, ainsi que KLIPY_APP_KEY, dans l’environnement (ou dans un .env à côté du serveur). Une valeur vide désactive cette fonctionnalité plutôt que de faire échouer le démarrage.

--sandbox

Le serveur sonde l’hôte une fois au démarrage et encapsule l’exécution des commandes d’agent dans le bac à sable natif du système d’exploitation lorsqu’un backend est disponible : sandbox-exec (Seatbelt) sous macOS, bwrap plus socat sous Linux et WSL2. Là où il n’y en a aucun — Windows, ou un hôte Linux dépourvu de ces outils —, les exécutions se rabattent sur l’assainissement de l’environnement, la politique de commandes et les garde-fous d’action, et le journal de démarrage indique l’état applicable.

--sandbox off est l’interrupteur de coupure en production pour le cas que la sonde ne peut pas voir : un hôte où le profil de bac à sable lui-même se comporte mal. Il ne nécessite aucune reconstruction, et le serveur consigne un avertissement pendant toute la durée de vie du processus pour que cet état ne soit jamais silencieux.

--tool-deferral

Les exécutions du harnais intégré envoient un petit ensemble résident de définitions d’outils ainsi qu’un index de noms du reste, dont les schémas se chargent à la première utilisation. Cela réduit le bloc d’outils d’environ 78 % et maintient l’ensemble toujours visible dans la plage où les modèles sélectionnent les outils de façon fiable. Les outils différés restent appelables par leur nom à tout moment, et search_tools les retrouve par intention. Voir Contexte des outils et cache de prompts.

--tool-deferral off rend de nouveau résident chaque outil admis, ce qui reproduit exactement les requêtes que le serveur émettait avant l’existence de la mise en différé. C’est l’interrupteur de coupure pour un modèle qui gère mal la surface à deux niveaux — un drapeau plutôt qu’une reconstruction. Il n’affecte que le harnais intégré ; le tools/list MCP que voient les clients externes reste toujours le catalogue complet.

--credential-gate

Une exécution dont l’identifiant de fournisseur est absent ou épuisé est mise en attente plutôt que mise en échec : l’opérateur reçoit une invite pour le corriger, et l’exécution reprend s’il le fait. Le délai par défaut est de 900 secondes (15 minutes), borné à 0–3600.

Le délai est délibérément bien plus long que celui de l’invite d’approbation : une approbation est une décision qui se prend en quelques secondes, tandis que corriger un identifiant suppose d’ouvrir un terminal, de se connecter et de revenir. Le plafond évite qu’une exécution non surveillée — une étape de pipeline, un déclencheur cron, un webhook — attende quelqu’un qui dort. À son expiration, l’exécution échoue avec le message qui aurait été le sien de toute façon.

--credential-gate=0 est l’interrupteur de coupure : rien n’est jamais mis en attente et un identifiant invalide met fin au tour exactement comme avant l’existence de cette barrière.

Sous-commandes

Commande	Ce qu’elle fait
cc_server	Exécute le serveur jusqu’à SIGINT/SIGTERM
cc_server pair	Provisionne un appareil et affiche son identifiant et sa clé d’appairage. Sans risque vis-à-vis d’un répertoire de données qu’un serveur sert déjà — le serveur en cours d’exécution prend l’appareil en compte sans redémarrage
cc_server calendar connect --workspace <id>	Connecte un compte Google à un espace de travail via le flux à code d’appareil, puis se termine
cc_server update	Recherche, télécharge et vérifie une version publiée autonome plus récente
cc_server --version	Affiche la version de compilation et le SHA git — la même identité que celle qu’annoncent /healthz et la poignée de main RPC

pair

Drapeau	Défaut	Signification
--device	web-client	L’identifiant d’appareil. La plateforme en est déduite, si bien que --device desktop émet une ligne de bureau et --device ios/android une ligne de téléphone ; toute autre valeur est traitée comme web
--label	le nom de la plateforme suivi du nom d’hôte de cette machine	Nom d’affichage dans la liste des appareils
--host	localhost, ou <this-host> en cas de liaison à toutes les interfaces	Hôte à intégrer dans l’URL affichée. Définissez-le sur l’IP du réseau local ou l’hôte du tunnel qu’un client joindra réellement
--client-url	non défini	Origine du client web hébergé. Ajoute un lien profond scannable et un QR code pour le terminal

pair accepte aussi les drapeaux principaux --data-dir, --port et --bind : ils sélectionnent le répertoire de données où écrire et déterminent la forme de l’URL de serveur affichée (ws sur la boucle locale, wss avec --bind any). Relancer pair pour le même --device renouvelle sa clé et met fin aux sessions actives de cet appareil. Un identifiant émis ici n’a aucune expiration, contrairement aux 30 jours que fixe un appairage depuis l’application.

Le QR code de --client-url n’est pas le QR code du téléphone

pair --client-url remplit le formulaire de connexion du client web (URL du serveur, identifiant d’appareil et clé dans le fragment d’URL). Le téléphone s’appaire avec une charge utile différente, émise depuis le panneau d’appairage de l’application — le descripteur de connexion complet du serveur, plus une expiration. Les deux ne sont pas interchangeables — voir Associer un appareil.

update

--apply remplace l’installation ; il est refusé tant qu’un serveur répond encore sur le port configuré, sauf si vous passez --force. --allow-downgrade autorise une version publiée plus ancienne.

La commande refuse d’emblée, avec une explication plutôt qu’une erreur, les installations qu’elle ne possède pas :

Environnement	Détecté par	Ce qu’elle indique
Le serveur embarqué du bureau	CC_EMBEDDED=1 ou CC_BOOTSTRAP_DEVICE_ID	Mettez plutôt à jour l’application — l’installateur remplace toute l’arborescence
Un checkout de source lancé par dart run	le chemin du script se termine par .dart	Mettez-le à jour avec git
Docker	les marqueurs de conteneur	Récupérez une image plus récente

Cycle de vie du processus

cc_server s’exécute jusqu’à SIGINT / SIGTERM. Une variable d’environnement supplémentaire régit ce comportement, et c’est le bureau qui la définit, pas vous :

Variable	Effet
CC_EXIT_WITH_PARENT=1	Le serveur se termine quand son processus parent se termine, ce que l’on détecte lorsque le parent ferme l’extrémité d’écriture de son tube stdin. Le bureau la définit pour qu’une application plantée ne laisse jamais un serveur orphelin retenir le répertoire de données

Ne la définissez vous-même que si vous supervisez cc_server comme processus enfant et souhaitez la même garantie.

Organisation du répertoire de données

Le répertoire de données par défaut est ~/Library/Application Support/control-center sous macOS, %APPDATA%\control-center sous Windows et $XDG_DATA_HOME/control-center (sinon ~/.local/share/control-center) ailleurs. Un .cc_server relatif au répertoire courant n’est utilisé que lorsqu’aucun répertoire personnel ou de données applicatives ne peut être résolu.

Chemin	Contenu
global.db	Le registre des espaces de travail, les utilisateurs, les appareils appairés, le fil d’actualités et la file de la flotte
<workspaceId>/workspace.db	Une base de données par espace de travail — agents, espaces, tickets, mémoire, graphe de code
<workspaceId>/chat_credentials/	Jetons de bot de chat, en JSON brut, pour qu’ils suivent l’espace de travail
secrets.json	Clés d’appairage, identité applicative du fournisseur, jetons par utilisateur et jetons Google, SSO (0600)
backups/<timestamp>/	Un instantané d’installation — manifest.json, global.db et une copie de chaque espace de travail
backups/exports/	Exports d’un seul espace de travail, <workspaceId>-<timestamp>.db
backups/transfer/	Zone de transit pour les téléchargements et les envois de sauvegarde ; balayée par la route qui l’écrit
models/	Modèles de plongement, de séparation des locuteurs et de reconnaissance vocale, exécutés sur l’appareil
meetings/<meetingId>/	Audio de réunion conservé
rigs/images/	Images disque de rig importées (la surface de bureau QEMU)
rigs/smolvm/<rigId>/	État d’exécution de la microVM par rig (le secret du courtier, 0600)
rigs/smolvm-packs/	Paquets machine pré-extraits — le cache qui rend rapides les démarrages répétés de rig
rigs/tls/	L’autorité de certification du domaine de développement pour le HTTPS des rigs (clés 0600)
rigs/run/<rigId>/	Superpositions QEMU, images d’amorçage et clés par VM (0600)

Voir aussi

• Exécuter un serveur sans interface — la procédure d’installation à laquelle ces drapeaux appartiennent
• Exécuter un worker de flotte — le binaire cc_worker distinct qui s’enregistre auprès de ce serveur
• Sauvegarder et restaurer — copier ce répertoire en lieu sûr
• Sauvegarde, export et import — l’organisation de l’instantané et toutes les opérations de sauvegarde
• Se connecter à un serveur distant — pointer un client vers un serveur
• Déploiement et clients — pourquoi le serveur détient tout