Pular para o conteúdo
Control Center
Dar estrela ao repositório5Baixar
Menu

CLI do cc_server

Toda flag de processo aceita uma flag de CLI ou uma variável de ambiente; a flag tem precedência, depois o ambiente, depois o padrão. Credenciais de terceiros são a exceção — veja abaixo.

Opções principais

Seção intitulada “Opções principais”
Flag Env Padrão Significado
--data-dir CC_SERVER_DATA_DIR o diretório de dados de aplicativo por usuário do SO (veja abaixo) Bancos de dados, segredos, modelos e mídia em cache
--port CC_SERVER_PORT 9030 Porta TCP (0 = efêmera)
--bind CC_SERVER_BIND loopback loopback, ou any/all/0.0.0.0 para todas as interfaces (precisa de TLS ou --insecure)
--repo-roots CC_SERVER_REPO_ROOTS o diretório home do usuário do servidor Diretórios base separados por vírgula que um cliente pode navegar ao registrar um repo. Navegar acima de uma raiz é recusado
--log-level CC_SERVER_LOG_LEVEL warning debug, info, warning ou error. As linhas de inicialização e de pronto sempre são impressas
--server-name CC_SERVER_NAME o hostname da máquina Nome exibido em seletores, na descoberta e nas superfícies de emparelhamento

Acessibilidade e TLS

Seção intitulada “Acessibilidade e TLS”
Flag Env Padrão Significado
--tls-cert CC_SERVER_TLS_CERT não definido Cadeia de certificados PEM. Serve wss:// no próprio processo quando definida junto com a chave
--tls-key CC_SERVER_TLS_KEY não definido Chave privada PEM correspondente ao certificado
--insecure CC_SERVER_INSECURE desativado Permite uma vinculação em texto simples fora do loopback. Somente atrás de um proxy que termina o TLS em uma rede confiável; ignorado quando o TLS está configurado
--public-url CC_SERVER_PUBLIC_URL derivado da vinculação A URL de RPC que este servidor anuncia aos clientes emparelhados. Defina-a explicitamente atrás de um proxy, NAT ou túnel — o padrão é apenas um palpite sobre a vinculação local
--allowed-origins CC_SERVER_ALLOWED_ORIGINS https://app.usectrl.dev Origens de navegador separadas por vírgula autorizadas a discar /rpc a partir de outra origem. Clientes de loopback e nativos são sempre permitidos
--web-client-url CC_SERVER_WEB_CLIENT_URL não definido Origem do cliente web hospedado para o qual os callbacks de logon único retornam
--signaling-url CC_SERVER_SIGNALING_URL wss://signaling.usectrl.dev O broker de relay no qual este servidor entra para que um telefone consiga alcançá-lo sem um caminho direto
--mdns CC_SERVER_MDNS auto Anúncio na LAN: auto (apenas quando vinculado além do loopback), on, off. A descoberta anuncia apenas a existência — conectar-se ainda exige emparelhamento
--tunnel CC_SERVER_TUNNEL off Provedor de túnel gerenciado: off, cloudflared, ngrok, tailscale. A exposição pública é opcional
--tunnel-binary CC_SERVER_TUNNEL_BINARY resolvido a partir do PATH Caminho explícito do binário do túnel
--tunnel-sha256 CC_SERVER_TUNNEL_SHA256 não definido SHA-256 esperado desse binário, verificado antes de cada criação de processo
--tunnel-args CC_SERVER_TUNNEL_ARGS vazio Argumentos extras, separados por vírgula, para a invocação do túnel

Indexação e credenciais de terceiros

Seção intitulada “Indexação e credenciais de terceiros”
Flag Env Padrão Significado
--sandbox CC_SERVER_SANDBOX on Se as execuções de agentes são envolvidas no sandbox nativo do SO do host quando há um disponível. Uma opção de desativação, não de ativação — veja abaixo
--code-index CC_SERVER_CODE_INDEX on Interruptor de desligamento de campo para a indexação do grafo de código em segundo plano. off inicia limpo, sem recompilar
--code-index-defer CC_SERVER_CODE_INDEX_DEFER 15 Segundos de espera antes da primeira varredura de indexação depois do banner de pronto (limitado a 0–300)
--tool-deferral CC_SERVER_TOOL_DEFERRAL on Se as execuções do harness enviam um pequeno conjunto residente de ferramentas mais um índice de nomes, carregando o restante no primeiro uso. Veja abaixo
--credential-gate CC_SERVER_CREDENTIAL_GATE 900 Segundos que uma execução fica estacionada aguardando que uma pessoa corrija uma credencial que não consegue atendê-la (limitado a 0–3600). Veja abaixo

Um valor vazio para uma credencial é lido como não definido, então o fallback integrado continua valendo. Uma build a partir do código-fonte não traz nenhuma credencial integrada.

O Google Calendar e o seletor de GIFs do Klipy são exclusivos de variável de ambiente — não existe uma flag --google-client-id / --klipy-app-key (flags desconhecidas são ignoradas). Defina GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET, e KLIPY_APP_KEY, no ambiente (ou em um .env ao lado do servidor). Um valor vazio desativa o recurso em vez de falhar na inicialização.

--sandbox

Seção intitulada “--sandbox”

O servidor sonda o host uma vez na inicialização e envolve a execução de comandos dos agentes no sandbox nativo do SO quando há um backend disponível: sandbox-exec (Seatbelt) no macOS, bwrap mais socat no Linux e no WSL2. Onde não há nenhum — Windows, ou um host Linux sem essas ferramentas —, as execuções recorrem à sanitização do ambiente, à política de comandos e às barreiras de ação, e o log de inicialização informa qual estado se aplica.

--sandbox off é o interruptor de desligamento de campo para o caso que a sondagem não consegue ver: um host onde o próprio perfil de sandbox se comporta mal. Ele não exige recompilar, e o servidor registra um aviso durante toda a vida do processo, para que o estado nunca fique silencioso.

--tool-deferral

Seção intitulada “--tool-deferral”

As execuções do harness integrado enviam um pequeno conjunto residente de definições de ferramentas mais um índice apenas com os nomes do restante, que carregam seus esquemas na primeira vez em que são usados. Isso reduz o bloco de ferramentas em cerca de 78% e mantém o conjunto sempre visível dentro da faixa em que os modelos selecionam ferramentas de forma confiável. As ferramentas diferidas continuam chamáveis por nome o tempo todo, e search_tools as encontra por intenção. Consulte Contexto de ferramentas e cache de prompts.

--tool-deferral off torna residente novamente toda ferramenta admitida, reproduzindo as requisições que o servidor fazia antes de o diferimento existir. É o interruptor de desligamento para um modelo que lida mal com a superfície de dois níveis — uma flag, e não uma recompilação. Ele afeta apenas o harness integrado; o tools/list do MCP que os clientes externos veem é sempre o catálogo completo.

--credential-gate

Seção intitulada “--credential-gate”

Uma execução cuja credencial de provedor está ausente ou esgotada fica estacionada, em vez de falhar: o operador recebe um aviso para corrigi-la, e a execução é retomada se ele o fizer. O prazo padrão é de 900 segundos (15 minutos), limitado a 0–3600.

O prazo é deliberadamente muito maior do que o do aviso de aprovação: uma aprovação é uma decisão que alguém toma em segundos, enquanto corrigir uma credencial significa abrir um terminal, fazer login e voltar. O teto é o que impede que uma execução sem supervisão — uma etapa de pipeline, um gatilho de cron, um webhook — fique esperando alguém que está dormindo. Quando ele expira, a execução falha com a mensagem com que falharia de qualquer forma.

--credential-gate=0 é o interruptor de desligamento: nada nunca fica estacionado e uma credencial ruim encerra o turno exatamente como acontecia antes de esse bloqueio existir.

Subcomandos

Seção intitulada “Subcomandos”
Comando O que ele faz
cc_server Executa o servidor até SIGINT/SIGTERM
cc_server pair Provisiona um dispositivo e imprime o id e a chave de emparelhamento dele. Seguro em relação a um diretório de dados que um servidor já está atendendo — o servidor em execução reconhece o dispositivo sem reiniciar
cc_server calendar connect --workspace <id> Conecta uma conta do Google a um espaço de trabalho pelo fluxo de código de dispositivo e então encerra
cc_server update Verifica, baixa e valida uma versão autônoma mais recente
cc_server --version Imprime a versão da build e o SHA do git — a mesma identidade que /healthz e o handshake de RPC anunciam

pair

Seção intitulada “pair”
Flag Padrão Significado
--device web-client O id do dispositivo. A plataforma é inferida a partir dele, então --device desktop cria uma linha de desktop e --device ios/android uma linha de telefone; qualquer outra coisa é tratada como web
--label nome da plataforma mais o hostname desta máquina Nome de exibição na lista de dispositivos
--host localhost, ou <this-host> quando vinculado a qualquer interface Host a incorporar na URL impressa. Defina-o como o IP da LAN ou o host do túnel que um cliente realmente vai acessar
--client-url não definido Origem do cliente web hospedado. Adiciona um link direto escaneável e um QR no terminal

O pair também aceita as flags principais --data-dir, --port e --bind: elas selecionam o diretório de dados em que gravar e moldam a URL de servidor impressa (ws no loopback, wss com --bind any). Executar pair de novo para o mesmo --device rotaciona a chave dele e derruba as sessões ativas desse dispositivo. Uma credencial emitida aqui não tem expiração, ao contrário dos 30 dias que um emparelhamento feito no app define.

update

Seção intitulada “update”

--apply substitui a instalação; ele é recusado enquanto um servidor ainda responder na porta configurada, a menos que você passe --force. --allow-downgrade permite uma versão mais antiga.

Para instalações que não são dele, o comando recusa de imediato, com uma explicação em vez de um erro:

Ambiente Detectado por O que ele diz
O servidor embutido do desktop CC_EMBEDDED=1 ou CC_BOOTSTRAP_DEVICE_ID Atualize o app em vez disso — o instalador troca a árvore inteira
Um checkout do código-fonte iniciado com dart run o caminho do script termina em .dart Atualize-o com git
Docker marcadores de contêiner Baixe uma imagem mais recente

Ciclo de vida do processo

Seção intitulada “Ciclo de vida do processo”

O cc_server roda até SIGINT / SIGTERM. Uma variável de ambiente extra governa isso, e ela é definida pelo desktop, não por você:

Variável Efeito
CC_EXIT_WITH_PARENT=1 O servidor encerra quando o processo pai encerra, detectado quando o pai fecha a ponta de escrita do pipe de stdin. O desktop a define para que um app que travou nunca deixe um servidor órfão segurando o diretório de dados

Defina-a você mesmo apenas se estiver supervisionando o cc_server como processo filho e quiser a mesma garantia.

Layout do diretório de dados

Seção intitulada “Layout do diretório de dados”

O diretório de dados padrão é ~/Library/Application Support/control-center no macOS, %APPDATA%\control-center no Windows e $XDG_DATA_HOME/control-center (ou então ~/.local/share/control-center) nos demais. Um .cc_server relativo ao cwd só é usado quando nenhum diretório home ou de dados de aplicativo é resolvido.

Caminho Conteúdo
global.db O registro de espaços de trabalho, usuários, dispositivos emparelhados, o feed de notícias e a fila da frota
<workspaceId>/workspace.db Um banco de dados por espaço de trabalho — agentes, espaços, tickets, memória, o grafo de código
<workspaceId>/chat_credentials/ Tokens de bots de chat, em JSON simples, para que acompanhem o espaço de trabalho
secrets.json Chaves de emparelhamento, a identidade do app junto ao provedor, tokens por usuário e do Google, SSO (0600)
backups/<timestamp>/ Um snapshot da instalação — manifest.json, global.db e uma cópia de cada espaço de trabalho
backups/exports/ Exportações de um único espaço de trabalho, <workspaceId>-<timestamp>.db
backups/transfer/ Área de preparação para downloads e uploads de backup; varrida pela rota que grava nela
models/ Modelos de embedding, diarização e fala no dispositivo
meetings/<meetingId>/ Áudio de reunião retido
rigs/images/ Imagens de disco de rig importadas (a superfície de desktop do QEMU)
rigs/smolvm/<rigId>/ Estado de runtime da microVM por rig (o segredo do broker, 0600)
rigs/smolvm-packs/ Pacotes de máquina pré-extraídos — o cache que torna rápidas as inicializações repetidas de rig
rigs/tls/ A autoridade certificadora do domínio de desenvolvimento para o HTTPS dos rigs (chaves 0600)
rigs/run/<rigId>/ Overlays do QEMU, imagens semente e chaves por VM (0600)

Veja também

Seção intitulada “Veja também”

Preferências da documentação

Aparência
Idioma
Português (Brasil)