CLI de cc_server

Cada flag del proceso se da como flag de CLI o como variable de entorno: gana el flag, después la variable de entorno y, por último, el valor predeterminado. Las credenciales de terceros son la excepción — consulta más abajo.

Los flags desconocidos se ignoran en silencio

El analizador de argumentos está hecho a mano y se salta todo lo que no reconoce, así que una errata (--tls-key-file, --bindany) no produce ningún error — el servidor simplemente arranca con el valor predeterminado. Revisa las líneas del registro de arranque cuando un flag parezca no tener efecto.

Opciones principales

Flag	Variable de entorno	Predeterminado	Significado
--data-dir	CC_SERVER_DATA_DIR	el directorio de datos de aplicación por usuario del sistema operativo (ver abajo)	Bases de datos, secretos, modelos y medios en caché
--port	CC_SERVER_PORT	9030	Puerto TCP (0 = efímero)
--bind	CC_SERVER_BIND	loopback	loopback, o any/all/0.0.0.0 para todas las interfaces (necesita TLS o --insecure)
--repo-roots	CC_SERVER_REPO_ROOTS	el directorio personal del usuario del servidor	Directorios base separados por comas que un cliente puede explorar al registrar un repo. Se rechaza explorar por encima de una raíz
--log-level	CC_SERVER_LOG_LEVEL	warning	debug, info, warning o error. Las líneas de arranque y de preparado siempre se imprimen
--server-name	CC_SERVER_NAME	el nombre de host de la máquina	Nombre que se muestra en los selectores, el descubrimiento y las pantallas de emparejamiento

Alcanzabilidad y TLS

Flag	Variable de entorno	Predeterminado	Significado
--tls-cert	CC_SERVER_TLS_CERT	sin definir	Cadena de certificados PEM. Sirve wss:// en el propio proceso cuando se define junto con la clave
--tls-key	CC_SERVER_TLS_KEY	sin definir	Clave privada PEM que corresponde al certificado
--insecure	CC_SERVER_INSECURE	off	Permite un enlace en texto plano fuera de loopback. Solo detrás de un proxy que termine TLS en una red de confianza; se ignora cuando hay TLS configurado
--public-url	CC_SERVER_PUBLIC_URL	derivado del enlace	La URL de RPC que este servidor anuncia a los clientes emparejados. Defínela explícitamente detrás de un proxy, un NAT o un túnel — el valor predeterminado solo es una conjetura a partir del enlace local
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	Orígenes de navegador separados por comas a los que se permite llamar a /rpc entre orígenes. Loopback y los clientes nativos siempre están permitidos
--web-client-url	CC_SERVER_WEB_CLIENT_URL	sin definir	Origen del cliente web alojado al que vuelven las devoluciones de llamada del inicio de sesión único
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	El relé al que se une este servidor para que un teléfono pueda alcanzarlo cuando no hay una ruta directa
--mdns	CC_SERVER_MDNS	auto	Anuncio en la LAN: auto (solo cuando se enlaza más allá de loopback), on, off. El descubrimiento solo anuncia la existencia: unirse sigue exigiendo emparejamiento
--tunnel	CC_SERVER_TUNNEL	off	Proveedor de túnel gestionado: off, cloudflared, ngrok, tailscale. La exposición pública hay que activarla explícitamente
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	resuelto desde PATH	Ruta explícita del binario del túnel
--tunnel-sha256	CC_SERVER_TUNNEL_SHA256	sin definir	SHA-256 esperado de ese binario, verificado antes de cada arranque
--tunnel-args	CC_SERVER_TUNNEL_ARGS	vacío	Argumentos adicionales separados por comas para la invocación del túnel

Indexación y credenciales de terceros

Flag	Variable de entorno	Predeterminado	Significado
--sandbox	CC_SERVER_SANDBOX	on	Si las ejecuciones de agentes se envuelven en el entorno aislado nativo del sistema operativo del host cuando hay uno disponible. Es una opción de desactivación, no de activación — consulta más abajo
--code-index	CC_SERVER_CODE_INDEX	on	Interruptor de emergencia sobre el terreno para la indexación en segundo plano del grafo de código. off arranca limpio sin recompilar
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	Segundos que se retrasa el primer barrido de indexación tras el aviso de preparado (acotado entre 0 y 300)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	Si las ejecuciones del arnés envían un pequeño conjunto residente de herramientas más un índice de nombres y cargan el resto en el primer uso. Consulta más abajo
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	Segundos que una ejecución queda aparcada esperando a que una persona arregle una credencial que no puede servirla (acotado entre 0 y 3600). Consulta más abajo

Un valor vacío en una credencial se interpreta como no definido, así que el mecanismo de reserva integrado sigue aplicándose. Una compilación desde el código fuente no incluye ninguna credencial integrada.

Google Calendar y el selector de GIF de Klipy son solo por variables de entorno — no existe ningún flag --google-client-id / --klipy-app-key (los flags desconocidos se ignoran). Define GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET, y KLIPY_APP_KEY, en el entorno (o en un .env junto al servidor). Un valor vacío desactiva esa función en lugar de hacer fallar el arranque.

--sandbox

El servidor sondea el host una vez al arrancar y envuelve la ejecución de comandos de los agentes en el entorno aislado nativo del sistema operativo cuando hay un backend disponible: sandbox-exec (Seatbelt) en macOS, y bwrap más socat en Linux y WSL2. Donde no lo hay —Windows, o un host Linux al que le faltan esas herramientas—, las ejecuciones recurren al saneamiento del entorno, la política de comandos y las barandillas de acción, y el registro de arranque indica qué estado se aplica.

--sandbox off es el interruptor de emergencia sobre el terreno para el caso que la sonda no puede ver: un host en el que el propio perfil del entorno aislado se comporta mal. No necesita recompilarse, y el servidor registra una advertencia durante toda la vida del proceso para que el estado nunca pase desapercibido.

--tool-deferral

Las ejecuciones del arnés integrado envían un pequeño conjunto residente de definiciones de herramientas más un índice con solo los nombres del resto, cuyos esquemas se cargan la primera vez que se usan. Recorta el bloque de herramientas en torno a un 78 % y mantiene el conjunto siempre visible dentro del rango en el que los modelos seleccionan herramientas de forma fiable. Las herramientas diferidas siguen siendo invocables por su nombre en todo momento, y search_tools las encuentra por intención. Consulta Contexto de herramientas y caché de prompts.

--tool-deferral off vuelve a hacer residentes todas las herramientas admitidas, reproduciendo las peticiones que el servidor hacía antes de que existiera la carga diferida. Es el interruptor de emergencia para un modelo que lleva mal la superficie de dos niveles: un flag en lugar de una recompilación. Solo afecta al arnés integrado; el tools/list de MCP que ven los clientes externos es siempre el catálogo completo.

--credential-gate

Una ejecución cuya credencial de proveedor falta o está agotada se aparca en lugar de fallar: el operador recibe un aviso para arreglarla, y la ejecución se reanuda si lo hace. El plazo predeterminado es de 900 segundos (15 minutos), acotado entre 0 y 3600.

El plazo es deliberadamente mucho más largo que el del aviso de aprobación: una aprobación es una decisión que alguien toma en segundos, mientras que arreglar una credencial implica abrir un terminal, iniciar sesión y volver. Ese techo es lo que evita que una ejecución desatendida —un paso de pipeline, un disparador de cron, un webhook— se quede esperando a alguien que está durmiendo. Cuando vence, la ejecución falla con el mensaje con el que habría fallado de todos modos.

--credential-gate=0 es el interruptor de emergencia: nunca se aparca nada y una credencial defectuosa termina el turno exactamente como lo hacía antes de que existiera esta puerta.

Subcomandos

Comando	Qué hace
cc_server	Ejecuta el servidor hasta que recibe SIGINT/SIGTERM
cc_server pair	Aprovisiona un dispositivo e imprime su id y su clave de emparejamiento. Es seguro aunque un servidor ya esté sirviendo ese directorio de datos — el servidor en ejecución detecta el dispositivo sin reiniciarse
cc_server calendar connect --workspace <id>	Conecta una cuenta de Google a un espacio de trabajo mediante el flujo de código de dispositivo y luego termina
cc_server update	Busca, descarga y verifica una versión independiente más reciente
cc_server --version	Imprime la versión de compilación y el SHA de git — la misma identidad que anuncian /healthz y el handshake de RPC

pair

Flag	Predeterminado	Significado
--device	web-client	El id del dispositivo. La plataforma se infiere de él, así que --device desktop crea una fila de escritorio y --device ios/android una fila de teléfono; cualquier otro valor se trata como web
--label	el nombre de la plataforma más el nombre de host de esta máquina	Nombre visible en la lista de dispositivos
--host	localhost, o <this-host> cuando se enlaza a cualquier interfaz	Host que se incluye en la URL impresa. Defínelo con la IP de la LAN o el host del túnel al que un cliente se conectará de verdad
--client-url	sin definir	Origen del cliente web alojado. Añade un enlace directo escaneable y un QR de terminal

pair también acepta los flags principales --data-dir, --port y --bind: seleccionan el directorio de datos en el que escribir y determinan la forma de la URL de servidor que se imprime (ws en loopback, wss con --bind any). Volver a ejecutar pair para el mismo --device rota su clave y corta las sesiones activas de ese dispositivo. Una credencial generada aquí no caduca, a diferencia de los 30 días que fija un emparejamiento hecho desde la aplicación.

El QR de --client-url no es el QR del teléfono

pair --client-url rellena el formulario de conexión del cliente web (URL del servidor, id de dispositivo y clave en el fragmento de la URL). El teléfono se empareja con una carga útil distinta, generada desde el panel de emparejamiento de la aplicación — el descriptor de conexión completo del servidor más una caducidad. Las dos no son intercambiables — consulta Emparejar un dispositivo.

update

--apply sustituye la instalación; se rechaza mientras un servidor siga respondiendo en el puerto configurado, salvo que pases --force. --allow-downgrade permite una versión anterior.

El comando se niega directamente, con una explicación en lugar de un error, ante instalaciones que no le pertenecen:

Entorno	Cómo se detecta	Qué dice
El servidor integrado del escritorio	CC_EMBEDDED=1 o CC_BOOTSTRAP_DEVICE_ID	Actualiza la aplicación en su lugar — el instalador sustituye todo el árbol
Un checkout del código fuente con dart run	la ruta del script termina en .dart	Actualízalo con git
Docker	marcadores de contenedor	Descarga una imagen más reciente

Ciclo de vida del proceso

cc_server se ejecuta hasta recibir SIGINT / SIGTERM. Lo controla una variable de entorno adicional, y la define el escritorio, no tú:

Variable	Efecto
CC_EXIT_WITH_PARENT=1	El servidor termina cuando lo hace su proceso padre, algo que se detecta porque el padre cierra el extremo de escritura de su tubería de stdin. El escritorio la define para que una aplicación que se cae nunca deje huérfano un servidor que retiene el directorio de datos

Defínela tú mismo solo si supervisas cc_server como proceso hijo y quieres esa misma garantía.

Estructura del directorio de datos

El directorio de datos predeterminado es ~/Library/Application Support/control-center en macOS, %APPDATA%\control-center en Windows y $XDG_DATA_HOME/control-center (o, si no, ~/.local/share/control-center) en el resto de sistemas. Solo se usa un .cc_server relativo al directorio de trabajo actual cuando no se resuelve ningún directorio home ni de datos de aplicación.

Ruta	Contenido
global.db	El registro de espacios de trabajo, los usuarios, los dispositivos emparejados, las noticias y la cola de la flota
<workspaceId>/workspace.db	Una base de datos por espacio de trabajo — agentes, espacios, tickets, memoria y el grafo de código
<workspaceId>/chat_credentials/	Tokens de bots de chat, en JSON simple, para que viajen con el espacio de trabajo
secrets.json	Claves de emparejamiento, la identidad de la app del proveedor, tokens por usuario y de Google, SSO (0600)
backups/<timestamp>/	Una instantánea por instalación — manifest.json, global.db y una copia de cada espacio de trabajo
backups/exports/	Exportaciones de un solo espacio de trabajo, <workspaceId>-<timestamp>.db
backups/transfer/	Zona de preparación para descargas y subidas de copias de seguridad; la limpia la ruta que escribe en ella
models/	Modelos de embeddings, diarización y voz en el propio dispositivo
meetings/<meetingId>/	Audio de reuniones conservado
rigs/images/	Imágenes de disco de rigs importadas (la superficie de escritorio QEMU)
rigs/smolvm/<rigId>/	Estado de ejecución del microVM de cada rig (el secreto del broker, 0600)
rigs/smolvm-packs/	Paquetes de máquina preextraídos — la caché que hace rápidos los arranques repetidos de un rig
rigs/tls/	La autoridad de certificación del dominio de desarrollo para HTTPS de los rigs (claves 0600)
rigs/run/<rigId>/	Superposiciones de QEMU, imágenes semilla y claves por VM (0600)

Consulta también

• Ejecutar un servidor headless — la receta de configuración a la que pertenecen estos flags
• Ejecutar un worker de flota — el binario cc_worker aparte que se registra en este servidor
• Hacer copia de seguridad y restaurar — copiar este directorio a un lugar seguro
• Copia de seguridad, exportación e importación — la estructura de las instantáneas y todas las operaciones de copia
• Conectar a un servidor remoto — apuntar un cliente a uno
• Despliegue y clientes — por qué el servidor lo posee todo