Salta ai contenuti
Control Center
Aggiungi una stella al repository5Scarica
Menu

CLI di cc_server

Ogni parametro del processo accetta un flag CLI o una variabile d’ambiente; vince il flag, poi l’ambiente, poi il valore predefinito. Le credenziali di terze parti sono l’eccezione — vedi sotto.

Base

Sezione intitolata “Base”
Flag Env Predefinito Significato
--data-dir CC_SERVER_DATA_DIR la directory dei dati applicativi per utente del sistema operativo (vedi sotto) Database, segreti, modelli e media in cache
--port CC_SERVER_PORT 9030 Porta TCP (0 = effimera)
--bind CC_SERVER_BIND loopback loopback, oppure any/all/0.0.0.0 per ogni interfaccia (richiede TLS o --insecure)
--repo-roots CC_SERVER_REPO_ROOTS la directory home dell’utente del server Directory di base separate da virgola in cui un client può navigare quando registra un repo. La navigazione sopra una root viene rifiutata
--log-level CC_SERVER_LOG_LEVEL warning debug, info, warning o error. Le righe di avvio e di pronto vengono sempre stampate
--server-name CC_SERVER_NAME il nome host della macchina Nome mostrato nei selettori, nel rilevamento e nelle schermate di associazione

Raggiungibilità e TLS

Sezione intitolata “Raggiungibilità e TLS”
Flag Env Predefinito Significato
--tls-cert CC_SERVER_TLS_CERT non impostato Catena di certificati PEM. Serve wss:// in-process quando è impostata insieme alla chiave
--tls-key CC_SERVER_TLS_KEY non impostato Chiave privata PEM corrispondente al certificato
--insecure CC_SERVER_INSECURE off Consente un bind non loopback in chiaro. Solo dietro un proxy che termina il TLS su una rete fidata; ignorato quando TLS è configurato
--public-url CC_SERVER_PUBLIC_URL derivato dal bind L’URL RPC che questo server pubblicizza ai client associati. Impostalo esplicitamente dietro un proxy, NAT o tunnel — il valore predefinito è solo una stima del bind locale
--allowed-origins CC_SERVER_ALLOWED_ORIGINS https://app.usectrl.dev Origini browser separate da virgola autorizzate a contattare /rpc cross-origin. I client loopback e nativi sono sempre consentiti
--web-client-url CC_SERVER_WEB_CLIENT_URL non impostato Origine del client web ospitato a cui rimbalzano i callback di accesso singolo
--signaling-url CC_SERVER_SIGNALING_URL wss://signaling.usectrl.dev Il broker di relay a cui questo server si unisce affinché un telefono possa raggiungerlo senza un percorso diretto
--mdns CC_SERVER_MDNS auto Annuncio in LAN: auto (solo quando è in ascolto oltre il loopback), on, off. Il rilevamento annuncia solo l’esistenza — per unirsi serve comunque l’associazione
--tunnel CC_SERVER_TUNNEL off Provider di tunnel gestito: off, cloudflared, ngrok, tailscale. L’esposizione pubblica è opt-in
--tunnel-binary CC_SERVER_TUNNEL_BINARY risolto da PATH Percorso esplicito del binario del tunnel
--tunnel-sha256 CC_SERVER_TUNNEL_SHA256 non impostato SHA-256 atteso di quel binario, verificato prima di ogni avvio
--tunnel-args CC_SERVER_TUNNEL_ARGS vuoto Argomenti extra separati da virgola per l’invocazione del tunnel

Indicizzazione e credenziali di terze parti

Sezione intitolata “Indicizzazione e credenziali di terze parti”
Flag Env Predefinito Significato
--sandbox CC_SERVER_SANDBOX on Se le esecuzioni degli agenti vengono avvolte nel sandbox nativo del sistema operativo dell’host quando ne è disponibile uno. Un opt-out, non un’abilitazione — vedi sotto
--code-index CC_SERVER_CODE_INDEX on Interruttore di emergenza sul campo per l’indicizzazione in background del grafo del codice. off si avvia pulito senza una ricompilazione
--code-index-defer CC_SERVER_CODE_INDEX_DEFER 15 Secondi di attesa prima della prima scansione di indicizzazione dopo il banner di pronto (limitato a 0–300)
--tool-deferral CC_SERVER_TOOL_DEFERRAL on Se le esecuzioni dell’harness inviano un piccolo set di strumenti residenti più un indice dei nomi, caricando il resto al primo uso. Vedi sotto
--credential-gate CC_SERVER_CREDENTIAL_GATE 900 Secondi in cui un’esecuzione resta parcheggiata in attesa che una persona corregga una credenziale che non può servirla (limitato a 0–3600). Vedi sotto

Un valore vuoto per una credenziale viene interpretato come non impostato, quindi si applica comunque il fallback integrato. Una build dai sorgenti non porta con sé alcuna credenziale integrata.

Google Calendar e il selettore di GIF Klipy sono solo tramite variabili d’ambiente — non esiste un flag --google-client-id / --klipy-app-key (i flag sconosciuti vengono ignorati). Imposta GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET e KLIPY_APP_KEY nell’ambiente (o in un .env accanto al server). Un valore vuoto disabilita quella funzione invece di far fallire l’avvio.

--sandbox

Sezione intitolata “--sandbox”

Il server sonda l’host una volta all’avvio e avvolge l’esecuzione dei comandi degli agenti nel sandbox nativo del sistema operativo quando è disponibile un backend: sandbox-exec (Seatbelt) su macOS, bwrap più socat su Linux e WSL2. Dove non ce n’è nessuno — Windows, o un host Linux privo di quegli strumenti — le esecuzioni ripiegano sulla sanificazione dell’ambiente, sulla policy dei comandi e sui guardrail delle azioni, e il log di avvio indica quale stato si applica.

--sandbox off è l’interruttore di emergenza sul campo per il caso che la sonda non riesce a vedere: un host in cui il profilo del sandbox stesso si comporta male. Non richiede una ricompilazione e il server registra un avviso per tutta la durata del processo, così lo stato non è mai silenzioso.

--tool-deferral

Sezione intitolata “--tool-deferral”

Le esecuzioni dell’harness integrato inviano un piccolo set residente di definizioni degli strumenti più un indice dei soli nomi del resto, che carica i propri schemi la prima volta che vengono usati. Riduce il blocco degli strumenti di circa il 78% e mantiene l’insieme sempre visibile entro l’intervallo in cui i modelli selezionano gli strumenti in modo affidabile. Gli strumenti differiti restano richiamabili per nome in ogni momento, e search_tools li trova per intento. Vedi Contesto degli strumenti e cache dei prompt.

--tool-deferral off rende di nuovo residente ogni strumento ammesso, riproducendo le richieste che il server faceva prima che esistesse il differimento. È l’interruttore di emergenza per un modello che gestisce male la superficie a due livelli — un flag invece di una ricompilazione. Influisce solo sull’harness integrato; il tools/list MCP visto dai client esterni è sempre il catalogo completo.

--credential-gate

Sezione intitolata “--credential-gate”

Un’esecuzione la cui credenziale del fornitore manca o è esaurita viene parcheggiata anziché fatta fallire: all’operatore viene mostrata una richiesta di correggerla, e l’esecuzione riprende se lo fa. La scadenza predefinita è di 900 secondi (15 minuti), limitata a 0–3600.

La scadenza è deliberatamente molto più lunga di quella della richiesta di approvazione: un’approvazione è una decisione che qualcuno prende in pochi secondi, mentre correggere una credenziale significa aprire un terminale, accedere e tornare. Il tetto massimo è ciò che impedisce a un’esecuzione non presidiata — un passaggio di pipeline, un trigger cron, un webhook — di aspettare qualcuno che dorme. Quando scade, l’esecuzione fallisce con il messaggio con cui sarebbe fallita comunque.

--credential-gate=0 è l’interruttore di emergenza: nulla viene mai parcheggiato e una credenziale non valida termina il turno esattamente come faceva prima che il gate esistesse.

Sottocomandi

Sezione intitolata “Sottocomandi”
Comando Cosa fa
cc_server Esegue il server fino a SIGINT/SIGTERM
cc_server pair Effettua il provisioning di un dispositivo e ne stampa l’id e la chiave di abbinamento. Sicuro su una directory dei dati che un server sta già servendo — il server in esecuzione rileva il dispositivo senza riavvio
cc_server calendar connect --workspace <id> Collega un account Google a uno spazio di lavoro tramite il flusso device-code, poi esce
cc_server update Cerca, scarica e verifica una release standalone più recente
cc_server --version Stampa la versione della build e lo SHA git — la stessa identità pubblicizzata da /healthz e dall’handshake RPC

pair

Sezione intitolata “pair”
Flag Predefinito Significato
--device web-client L’id del dispositivo. La piattaforma viene dedotta da esso, quindi --device desktop crea una riga desktop e --device ios/android una riga telefono; qualsiasi altro valore viene trattato come web
--label nome della piattaforma più il nome host di questa macchina Nome visualizzato nell’elenco dei dispositivi
--host localhost, oppure <this-host> quando è in ascolto su ogni interfaccia Host da incorporare nell’URL stampato. Impostalo sull’IP della LAN o sull’host del tunnel che un client contatterà davvero
--client-url non impostato Origine del client web ospitato. Aggiunge un deep link scansionabile e un QR da terminale

pair accetta anche i flag di base --data-dir, --port e --bind: selezionano la directory dei dati in cui scrivere e determinano l’URL del server stampato (ws su loopback, wss con --bind any). Rieseguire pair per lo stesso --device ruota la sua chiave e chiude le sessioni attive di quel dispositivo. Una credenziale generata qui non ha scadenza, a differenza dei 30 giorni impostati da un’associazione dall’app.

update

Sezione intitolata “update”

--apply sostituisce l’installazione; viene rifiutato finché un server risponde ancora sulla porta configurata, a meno che tu non passi --force. --allow-downgrade consente una release più vecchia.

Il comando rifiuta del tutto, con una spiegazione anziché un errore, le installazioni che non possiede:

Ambiente Rilevato da Cosa dice
Il server incorporato del desktop CC_EMBEDDED=1 o CC_BOOTSTRAP_DEVICE_ID Aggiorna invece l’app — l’installer sostituisce l’intero albero
Un checkout dei sorgenti con dart run il percorso dello script termina in .dart Aggiornalo con git
Docker indicatori del container Esegui il pull di un’immagine più recente

Ciclo di vita del processo

Sezione intitolata “Ciclo di vita del processo”

cc_server viene eseguito fino a SIGINT / SIGTERM. Una variabile d’ambiente aggiuntiva lo governa, ed è impostata dal desktop, non da te:

Variabile Effetto
CC_EXIT_WITH_PARENT=1 Il server esce quando esce il suo processo padre, rilevato dalla chiusura dell’estremità di scrittura della sua pipe stdin da parte del padre. Il desktop la imposta così un’app andata in crash non lascia mai un server orfano che occupa la directory dei dati

Impostala da solo solo se supervisioni cc_server come processo figlio e vuoi la stessa garanzia.

Struttura della directory dei dati

Sezione intitolata “Struttura della directory dei dati”

La directory dei dati predefinita è ~/Library/Application Support/control-center su macOS, %APPDATA%\control-center su Windows e $XDG_DATA_HOME/control-center (altrimenti ~/.local/share/control-center) altrove. Un .cc_server relativo alla cwd viene usato solo quando non si risolve alcuna directory home o dei dati applicativi.

Percorso Contenuto
global.db Il registro degli spazi di lavoro, gli utenti, i dispositivi associati, il feed di notizie e la coda della flotta
<workspaceId>/workspace.db Un database per spazio di lavoro — agenti, spazi, ticket, memoria, il grafo del codice
<workspaceId>/chat_credentials/ Token dei bot di chat, come JSON in chiaro, così seguono lo spazio di lavoro
secrets.json Chiavi di abbinamento, l’identità dell’app dei fornitori, i token per utente e quelli di Google, SSO (0600)
backups/<timestamp>/ Un’istantanea dell’installazione — manifest.json, global.db e una copia di ogni spazio di lavoro
backups/exports/ Esportazioni di singoli spazi di lavoro, <workspaceId>-<timestamp>.db
backups/transfer/ Banco di lavoro per i download e gli upload dei backup; ripulito dalla route che vi scrive
models/ Modelli di embedding, diarizzazione e parlato sul dispositivo
meetings/<meetingId>/ Audio delle riunioni conservato
rigs/images/ Immagini disco dei rig importate (la superficie desktop QEMU)
rigs/smolvm/<rigId>/ Stato di runtime delle microVM per rig (il segreto del broker, 0600)
rigs/smolvm-packs/ Pacchetti macchina pre-estratti — la cache che rende veloci gli avvii ripetuti dei rig
rigs/tls/ L’autorità di certificazione del dominio di sviluppo per l’HTTPS dei rig (chiavi 0600)
rigs/run/<rigId>/ Overlay QEMU, immagini seed e chiavi per VM (0600)

Vedi anche

Sezione intitolata “Vedi anche”

Preferenze della documentazione

Aspetto
Lingua
Italiano (Italia)