CLI do cc_server

Cada flag de processo aceita uma flag de CLI ou uma variável de ambiente; a flag tem prioridade, depois o ambiente e, por fim, o valor predefinido. As credenciais de terceiros são a exceção — veja abaixo.

As flags desconhecidas são ignoradas em silêncio

O analisador de argumentos é feito à mão e ignora tudo o que não reconhece, pelo que uma gralha (--tls-key-file, --bindany) não produz erro nenhum — o servidor arranca simplesmente com o valor predefinido. Verifique as linhas do registo de arranque quando uma flag parecer não ter efeito.

Principais

Flag	Ambiente	Predefinição	Significado
--data-dir	CC_SERVER_DATA_DIR	o diretório de dados de aplicação por utilizador do sistema operativo (veja abaixo)	Bases de dados, segredos, modelos e multimé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 (requer TLS ou --insecure)
--repo-roots	CC_SERVER_REPO_ROOTS	o diretório pessoal do utilizador do servidor	Diretórios base separados por vírgulas que um cliente pode explorar ao registar um repo. A exploração acima de uma raiz é recusada
--log-level	CC_SERVER_LOG_LEVEL	warning	debug, info, warning ou error. As linhas de arranque e de prontidão são sempre impressas
--server-name	CC_SERVER_NAME	o nome de anfitrião da máquina	Nome apresentado nos seletores, na deteção e nas superfícies de emparelhamento

Acessibilidade e TLS

Flag	Ambiente	Predefinição	Significado
--tls-cert	CC_SERVER_TLS_CERT	não definido	Cadeia de certificados PEM. Serve wss:// em processo quando definido em conjunto 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 associação não cifrada a um endereço que não seja de loopback. Apenas atrás de um proxy que termina TLS numa rede de confiança; ignorado quando o TLS está configurado
--public-url	CC_SERVER_PUBLIC_URL	derivado da associação	O URL de RPC que este servidor anuncia aos clientes emparelhados. Defina-o explicitamente atrás de um proxy, NAT ou túnel — a predefinição é apenas um palpite com base na associação local
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	Origens de navegador separadas por vírgulas autorizadas a contactar /rpc entre origens. O loopback e os clientes nativos são sempre permitidos
--web-client-url	CC_SERVER_WEB_CLIENT_URL	não definido	Origem do cliente web alojado para onde os callbacks de início de sessão único regressam
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	O broker de relay a que este servidor se junta para que um telemóvel o consiga alcançar sem um caminho direto
--mdns	CC_SERVER_MDNS	auto	Anúncio na LAN: auto (apenas quando associado para além do loopback), on, off. A deteção anuncia apenas a existência — entrar continua a exigir emparelhamento
--tunnel	CC_SERVER_TUNNEL	off	Fornecedor de túnel gerido: off, cloudflared, ngrok, tailscale. A exposição pública é uma opção explícita
--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 lançamento
--tunnel-args	CC_SERVER_TUNNEL_ARGS	vazio	Argumentos adicionais separados por vírgulas para a invocação do túnel

Indexação e credenciais de terceiros

Flag	Ambiente	Predefinição	Significado
--sandbox	CC_SERVER_SANDBOX	on	Se as execuções de agentes são envolvidas na sandbox nativa do sistema operativo do anfitrião quando existe uma disponível. Uma opção de exclusão, não uma ativação — veja abaixo
--code-index	CC_SERVER_CODE_INDEX	on	Interruptor de emergência no terreno para a indexação do grafo de código em segundo plano. off arranca de forma limpa, sem recompilação
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	Segundos de espera antes da primeira varredura de indexação após o banner de prontidão (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 resto na primeira utilização. Veja abaixo
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	Segundos que uma execução fica em espera à espera de que uma pessoa corrija uma credencial que não a consegue servir (limitado a 0–3600). Veja abaixo

Um valor vazio para uma credencial é lido como não definido, pelo que a alternativa incorporada continua a aplicar-se. Uma compilação a partir do código-fonte não traz credenciais incorporadas nenhumas.

O Google Calendar e o seletor de GIFs Klipy são exclusivos do ambiente — não existe a flag --google-client-id / --klipy-app-key (as flags desconhecidas são ignoradas). Defina GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET e KLIPY_APP_KEY no ambiente (ou num .env ao lado do servidor). Um valor vazio desativa essa funcionalidade em vez de fazer falhar o arranque.

--sandbox

O servidor sonda o anfitrião uma vez no arranque e envolve a execução de comandos dos agentes na sandbox nativa do sistema operativo quando existe um backend disponível: sandbox-exec (Seatbelt) no macOS, bwrap mais socat no Linux e no WSL2. Onde não existe nenhum — no Windows, ou num anfitrião Linux sem essas ferramentas —, as execuções recaem na sanitização do ambiente, na política de comandos e nas barreiras de ação, e o registo de arranque indica qual o estado aplicável.

O --sandbox off é o interruptor de emergência no terreno para o caso que a sondagem não consegue ver: um anfitrião onde o próprio perfil de sandbox se comporta mal. Não precisa de recompilação e o servidor regista um aviso durante toda a vida do processo, para que o estado nunca fique em silêncio.

--tool-deferral

As execuções do harness integrado enviam um pequeno conjunto residente de definições de ferramentas mais um índice apenas de nomes do resto, que carregam os seus esquemas na primeira vez que são utilizadas. 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 fiável. As ferramentas diferidas continuam a poder ser chamadas pelo nome durante toda a execução, e o search_tools encontra-as por intenção. Ver Contexto de ferramentas e cache de prompts.

O --tool-deferral off volta a tornar residentes todas as ferramentas admitidas, reproduzindo os pedidos que o servidor fazia antes de o diferimento existir. É o interruptor de emergência para um modelo que lida mal com a superfície de dois níveis — uma flag em vez de uma recompilação. Afeta apenas o harness integrado; o tools/list do MCP que os clientes externos veem é sempre o catálogo completo.

--credential-gate

Uma execução cuja credencial de fornecedor está em falta ou esgotada fica em espera em vez de falhar: o operador recebe um pedido para a corrigir, e a execução retoma se o fizer. O prazo predefinido é 900 segundos (15 minutos), limitado a 0–3600.

O prazo é deliberadamente muito mais longo do que o do pedido de aprovação: uma aprovação é uma decisão que alguém toma em segundos, enquanto corrigir uma credencial implica abrir um terminal, iniciar sessão e voltar. É o limite máximo que impede uma execução sem supervisão — um passo de pipeline, um disparador cron, um webhook — de ficar à espera de alguém que está a dormir. Quando expira, a execução falha com a mensagem com que teria falhado de qualquer forma.

O --credential-gate=0 é o interruptor de emergência: nada fica alguma vez em espera e uma credencial inválida termina o turno exatamente como acontecia antes de o portão existir.

Subcomandos

Comando	O que faz
cc_server	Executa o servidor até SIGINT/SIGTERM
cc_server pair	Aprovisiona um dispositivo e imprime o seu id e a chave de emparelhamento. Seguro com um diretório de dados que um servidor já esteja a servir — o servidor em execução adota o dispositivo sem reiniciar
cc_server calendar connect --workspace <id>	Liga uma conta Google a um espaço de trabalho através do fluxo de código de dispositivo e, em seguida, sai
cc_server update	Verifica, transfere e valida uma versão autónoma mais recente
cc_server --version	Imprime a versão da compilação e o SHA do git — a mesma identidade que o /healthz e o handshake RPC anunciam

pair

Flag	Predefinição	Significado
--device	web-client	O id do dispositivo. A plataforma é inferida a partir dele, pelo que --device desktop cria uma linha de computador e --device ios/android uma linha de telemóvel; qualquer outra coisa é tratada como web
--label	o nome da plataforma mais o nome de anfitrião desta máquina	Nome apresentado na lista de dispositivos
--host	localhost, ou <this-host> quando associado a todas as interfaces	Anfitrião a incorporar no URL impresso. Defina-o como o IP da LAN ou o anfitrião do túnel que um cliente vai realmente contactar
--client-url	não definido	Origem do cliente web alojado. Acrescenta uma ligação profunda legível por código e um QR no terminal

O pair também aceita as flags principais --data-dir, --port e --bind: selecionam o diretório de dados onde escrever e moldam o URL do servidor impresso (ws em loopback, wss com --bind any). Voltar a executar o pair para o mesmo --device roda a sua chave e termina as sessões ativas desse dispositivo. Uma credencial emitida aqui não expira, ao contrário dos 30 dias definidos por um emparelhamento na aplicação.

O QR do --client-url não é o QR do telemóvel

O pair --client-url preenche o formulário de ligação do cliente web (URL do servidor, id do dispositivo e chave no fragmento do URL). O telemóvel emparelha com uma carga diferente emitida a partir do painel de emparelhamento na aplicação — o descritor de ligação completo do servidor mais um prazo de validade. Os dois não são intercambiáveis — ver Emparelhar um dispositivo.

update

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

O comando recusa liminarmente, com uma explicação em vez de um erro, para instalações que não lhe pertencem:

Ambiente	Detetado por	O que diz
O servidor incorporado do computador	CC_EMBEDDED=1 ou CC_BOOTSTRAP_DEVICE_ID	Atualize antes a aplicação — o instalador substitui toda a árvore
Uma cópia do código-fonte executada com dart run	o caminho do script termina em .dart	Atualize-a com o git
Docker	marcadores de contentor	Faça pull de uma imagem mais recente

Ciclo de vida do processo

O cc_server executa-se até SIGINT / SIGTERM. Uma variável de ambiente adicional controla isto, e é definida pelo computador e não por si:

Variável	Efeito
CC_EXIT_WITH_PARENT=1	O servidor termina quando o seu processo pai termina, detetado pelo fecho da extremidade de escrita do pipe stdin do pai. O computador define-a para que uma aplicação com falha nunca deixe um servidor órfão a segurar o diretório de dados

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

Estrutura do diretório de dados

O diretório de dados predefinido é ~/Library/Application Support/control-center no macOS, %APPDATA%\control-center no Windows e $XDG_DATA_HOME/control-center (ou ~/.local/share/control-center) nos restantes casos. Um .cc_server relativo ao diretório de trabalho atual só é utilizado quando não é possível resolver um diretório pessoal ou de dados de aplicação.

Caminho	Conteúdo
global.db	O registo de espaços de trabalho, utilizadores, dispositivos emparelhados, o feed de notícias e a fila da frota
<workspaceId>/workspace.db	Uma base 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 da aplicação do fornecedor, tokens por utilizador e do Google, SSO (0600)
backups/<timestamp>/	Um instantâneo 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 transferências e carregamentos de cópias de segurança; varrida pela rota que a escreve
models/	Modelos de embedding, diarização e fala no dispositivo
meetings/<meetingId>/	Áudio de reunião retido
rigs/images/	Imagens de disco de rigs importadas (a superfície de ambiente de trabalho QEMU)
rigs/smolvm/<rigId>/	Estado de execução do microVM por rig (o segredo do broker, 0600)
rigs/smolvm-packs/	Pacotes de máquina pré-extraídos — a cache que torna rápidos os arranques repetidos de rigs
rigs/tls/	A autoridade de certificação do domínio de desenvolvimento para o HTTPS dos rigs (chaves 0600)
rigs/run/<rigId>/	Sobreposições QEMU, imagens de arranque e chaves por VM (0600)

Ver também

• Executar um servidor headless — a receita de configuração a que pertencem estas flags
• Executar um worker da frota — o binário cc_worker separado que se regista neste servidor
• Fazer cópia de segurança e restaurar — copiar este diretório para um local seguro
• Cópia de segurança, exportação e importação — a estrutura dos instantâneos e todas as operações de cópia de segurança
• Ligar a um servidor remoto — apontar um cliente a um
• Implementação e clientes — porque é que o servidor é dono de tudo