CLI cc_server

Chaque paramètre du processus accepte une option de ligne de commande ou une variable d’environnement; l’option l’emporte, puis la variable d’environnement, puis la valeur par défaut. Les identifiants de tiers font exception — voir ci-dessous.

Les options inconnues sont ignorées en silence

L’analyseur d’arguments est écrit à la main et saute tout ce qu’il ne reconnaît pas, si bien qu’une coquille (--tls-key-file, --bindany) ne produit aucune erreur — le serveur démarre simplement avec la valeur par défaut. Vérifiez les lignes du journal de démarrage quand une option semble sans effet.

Fondamentaux

Option	Env	Valeur par défaut	Signification
--data-dir	CC_SERVER_DATA_DIR	le répertoire de données d’application par utilisateur du système d’exploitation (voir ci-dessous)	Bases de données, secrets, modèles et médias 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 qu’un client peut parcourir au moment d’enregistrer un dépôt. Tout parcours au-dessus d’une racine est refusé
--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’association

Joignabilité et TLS

Option	Env	Valeur par défaut	Signification
--tls-cert	CC_SERVER_TLS_CERT	non défini	Chaîne de certificats PEM. Sert wss:// au sein du 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 en clair hors loopback. Uniquement derrière un proxy qui termine 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 associés. Définissez-la explicitement derrière un proxy, un NAT ou un tunnel — la valeur par défaut n’est qu’une supposition à 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 inter-origine. Les clients loopback et natifs sont toujours autorisés
--web-client-url	CC_SERVER_WEB_CLIENT_URL	non défini	Origine du client web hébergé vers laquelle rebondissent les rappels d’ouverture de session unique
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	Le courtier de 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 (seulement en cas de liaison hors loopback), on, off. La découverte annonce uniquement l’existence — l’association reste nécessaire pour rejoindre
--tunnel	CC_SERVER_TUNNEL	off	Fournisseur de tunnel géré : off, cloudflared, ngrok, tailscale. L’exposition publique doit être activée explicitement
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	résolu depuis 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 de tiers

Option	Env	Valeur par défaut	Signification
--sandbox	CC_SERVER_SANDBOX	on	Indique si les exécutions d’agents sont encapsulées dans le bac à sable natif du système d’exploitation de l’hôte lorsqu’un tel bac à sable est disponible. Une désactivation, et non une activation — voir ci-dessous
--code-index	CC_SERVER_CODE_INDEX	on	Coupe-circuit à utiliser 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	Nombre de secondes pendant lesquelles la première passe d’indexation est retenue après la bannière de disponibilité (borné entre 0 et 300)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	Indique si les exécutions du harnais envoient un petit ensemble résident d’outils plus un index de noms, et chargent le reste à la première utilisation. Voir ci-dessous
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	Nombre de secondes pendant lesquelles une exécution reste en attente qu’une personne corrige un identifiant incapable de la servir (borné entre 0 et 3600). Voir ci-dessous

Une valeur vide pour un identifiant équivaut à une absence de définition, de sorte que le repli intégré s’applique quand même. Une compilation à partir du code source n’embarque aucun identifiant intégré.

Google Calendar et le sélecteur de GIF Klipy sont exclusivement des variables d’environnement — il n’existe aucune option --google-client-id / --klipy-app-key (les options inconnues sont ignorées). Définissez GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET, et 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 des agents dans le bac à sable natif du système d’exploitation lorsqu’un backend est disponible : sandbox-exec (Seatbelt) sur macOS, bwrap et socat sur Linux et WSL2. Là où il n’y en a pas — Windows, ou un hôte Linux auquel ces outils manquent —, 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 qui s’applique.

--sandbox off est le coupe-circuit à utiliser 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 n’exige aucune reconstruction et le serveur consigne un avertissement pendant toute la durée de vie du processus, de sorte que l’état n’est jamais silencieux.

--tool-deferral

Les exécutions du harnais intégré envoient un petit ensemble résident de définitions d’outils, plus un index qui ne contient que les 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 choisissent leurs outils de façon fiable. Les outils différés restent appelables par leur nom tout au long de l’exécution, et search_tools les trouve par intention. Voir Contexte des outils et cache de prompts.

--tool-deferral off rend de nouveau résidents tous les outils admis, reproduisant les requêtes que le serveur faisait avant l’existence du report. C’est le coupe-circuit pour un modèle qui gère mal la surface à deux niveaux — une option plutôt qu’une reconstruction. Il ne touche que le harnais intégré; le tools/list MCP que voient les clients externes correspond toujours au catalogue complet.

--credential-gate

Une exécution dont l’identifiant du fournisseur est absent ou épuisé est mise en attente plutôt que mise en échec : l’exploitant 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é entre 0 et 3600.

Ce délai est délibérément beaucoup 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. C’est le plafond qui empêche une exécution non surveillée — une étape de pipeline, un déclencheur cron, un webhook — d’attendre quelqu’un qui dort. À l’expiration, l’exécution échoue avec le message qui l’aurait fait échouer de toute façon.

--credential-gate=0 est le coupe-circuit : rien n’est jamais mis en attente et un mauvais identifiant met fin au tour exactement comme avant l’existence du contrôle.

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’association. Sans risque vis-à-vis d’un répertoire de données qu’un serveur dessert 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 par le flux de code d’appareil, puis quitte
cc_server update	Vérifie l’existence d’une nouvelle version autonome, la télécharge et la vérifie
cc_server --version	Affiche la version de compilation et le SHA git — la même identité qu’annoncent /healthz et la poignée de main RPC

pair

Option	Valeur par défaut	Signification
--device	web-client	L’identifiant de l’appareil. La plateforme en est déduite, de sorte que --device desktop génère une ligne de bureau et --device ios/android une ligne de téléphone; toute autre valeur est traitée comme le web
--label	le nom de la plateforme suivi du nom d’hôte de cette machine	Nom affiché dans la liste des appareils
--host	localhost, ou <this-host> en cas de liaison à toutes les interfaces	Hôte à intégrer à l’URL affichée. Définissez-le sur l’adresse 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 code QR dans le terminal

pair accepte aussi les options fondamentales --data-dir, --port et --bind : elles déterminent le répertoire de données à écrire et façonnent l’URL du serveur affichée (ws sur loopback, wss avec --bind any). Réexécuter pair pour le même --device fait tourner sa clé et ferme les sessions actives de cet appareil. Un identifiant généré ici n’a aucune expiration, contrairement aux 30 jours que fixe une association faite dans l’application.

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

pair --client-url remplit le formulaire de connexion du client web (URL du serveur, identifiant de l’appareil et clé dans le fragment de l’URL). Le téléphone s’associe avec une charge utile différente, générée à partir du panneau d’association 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; elle est refusée tant qu’un serveur répond encore sur le port configuré, à moins de passer --force. --allow-downgrade permet une version antérieure.

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

Environnement	Détecté par	Ce qu’elle dit
Le serveur intégré de l’application de bureau	CC_EMBEDDED=1 ou CC_BOOTSTRAP_DEVICE_ID	Mettez plutôt l’application à jour — l’installateur remplace tout l’arbre
Une copie de source dart run	le chemin du script se termine par .dart	Mettez-la à 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 l’application de bureau qui la définit, pas vous :

Variable	Effet
CC_EXIT_WITH_PARENT=1	Le serveur quitte lorsque son processus parent quitte, ce qui est détecté par la fermeture, par le parent, de l’extrémité d’écriture de son tube stdin. L’application de bureau la définit pour qu’une application plantée ne laisse jamais un serveur orphelin qui occupe 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 sur macOS, %APPDATA%\control-center sur Windows et $XDG_DATA_HOME/control-center (sinon ~/.local/share/control-center) ailleurs. Un .cc_server relatif au répertoire de travail courant n’est utilisé que lorsqu’aucun répertoire personnel ou de données d’application ne peut être résolu.

Chemin	Contenu
global.db	Le registre des espaces de travail, les utilisateurs, les appareils associés, le fil de nouvelles et la file d’attente 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 des robots de clavardage, en JSON brut, pour qu’ils suivent l’espace de travail
secrets.json	Clés d’association, identité d’application du fournisseur, jetons par utilisateur et Google, SSO (0600)
backups/<timestamp>/	Un instantané d’installation — manifest.json, global.db et une copie de chaque espace de travail
backups/exports/	Exportations d’un seul espace de travail, <workspaceId>-<timestamp>.db
backups/transfer/	Zone de transit pour les téléchargements et téléversements de sauvegardes; purgée par la route qui l’écrit
models/	Modèles d’incorporation, de diarisation et de reconnaissance vocale exécutés sur l’appareil
meetings/<meetingId>/	Audio de réunion conservé
rigs/images/	Images disque de rigs importées (la surface de bureau QEMU)
rigs/smolvm/<rigId>/	État d’exécution de la microVM de chaque rig (le secret du courtier, 0600)
rigs/smolvm-packs/	Paquets de machines préextraits — le cache qui accélère les démarrages répétés de rigs
rigs/tls/	L’autorité de certification du domaine de développement pour le HTTPS des rigs (clés 0600)
rigs/run/<rigId>/	Surcouches QEMU, images d’amorçage et clés par machine virtuelle (0600)

Voir aussi

• Exécuter un serveur sans interface — la recette d’installation à laquelle ces options 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 — la structure des instantanés et chaque opération de sauvegarde
• Se connecter à un serveur distant — y pointer un client
• Déploiement et clients — pourquoi le serveur détient tout