Ir al contenido
Control Center
Dar estrella al repositorio5Descargar
Menú

CLI de cc_server

Cada flag del proceso se puede dar como flag de CLI o como variable de entorno: gana el flag, luego la variable de entorno y al final el valor predeterminado. Las credenciales de terceros son la excepción — consulta más abajo.

Opciones principales

Sección titulada «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 home 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 computadora Nombre que se muestra en los selectores, el descubrimiento y las pantallas de emparejamiento

Alcanzabilidad y TLS

Sección titulada «Alcanzabilidad y TLS»
Flag Variable de entorno Predeterminado Significado
--tls-cert CC_SERVER_TLS_CERT sin definir Cadena de certificados PEM. Sirve wss:// dentro del 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 de 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 administrado: off, cloudflared, ngrok, tailscale. La exposición pública es opcional
--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

Sección titulada «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 sandbox 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 retiene el primer barrido de indexación después del aviso de preparado (acotado entre 0 y 300)
--tool-deferral CC_SERVER_TOOL_DEFERRAL on Si las ejecuciones del arnés envían un conjunto residente pequeño 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 en espera mientras alguien corrige una credencial que no puede servirle (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

Sección titulada «--sandbox»

El servidor sondea el host una vez al arrancar y envuelve la ejecución de comandos de los agentes en el sandbox 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 hay ninguno —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 donde el propio perfil del sandbox se comporta mal. No requiere recompilar y el servidor registra una advertencia durante toda la vida del proceso, así que el estado nunca queda en silencio.

--tool-deferral

Sección titulada «--tool-deferral»

Las ejecuciones del arnés integrado envían un conjunto residente pequeño de definiciones de herramientas más un índice que solo contiene 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 solicitudes 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

Sección titulada «--credential-gate»

Una ejecución a la que le falta la credencial de su proveedor, o que ya la agotó, queda en espera en lugar de fallar: el operador recibe un aviso para corregirla, 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 corregir una credencial implica abrir una 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á dormido. 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 pone nada en espera y una credencial defectuosa termina el turno exactamente como lo hacía antes de que existiera esta compuerta.

Subcomandos

Sección titulada «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

Sección titulada «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 computadora 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á en realidad
--client-url sin definir Origen del cliente web alojado. Agrega 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 donde escribir y determinan la forma de la URL del 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 app.

update

Sección titulada «update»

--apply reemplaza 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 de plano, con una explicación en lugar de un error, en el caso de 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 app en su lugar — el instalador reemplaza el árbol completo
Un checkout del código fuente con dart run la ruta del script termina en .dart Actualízalo con git
Docker marcadores del contenedor Descarga una imagen más reciente

Ciclo de vida del proceso

Sección titulada «Ciclo de vida del proceso»

cc_server se ejecuta hasta que recibe SIGINT / SIGTERM. Una variable de entorno adicional gobierna ese comportamiento, y la define el escritorio en lugar de ti:

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

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

Estructura del directorio de datos

Sección titulada «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 los 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, el feed de 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, como JSON simple, así que acompañan al 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/ Área de preparación para las descargas y cargas de respaldos; la limpia la ruta que escribe en ella
models/ Modelos de embeddings, diarización y voz que se ejecutan en el 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 en tiempo de ejecución de la microVM de cada rig (el secreto del broker, 0600)
rigs/smolvm-packs/ Paquetes de máquina preextraídos — la caché que agiliza los arranques repetidos de rigs
rigs/tls/ La autoridad certificadora del dominio de desarrollo para el HTTPS de los rigs (claves 0600)
rigs/run/<rigId>/ Overlays de QEMU, imágenes semilla y claves por VM (0600)

Ver también

Sección titulada «Ver también»

Preferencias de la documentación

Apariencia
Idioma
Español (México)