Conectar a um servidor remoto

Todo cliente é um renderizador sobre um cc_server que é dono dos dados. O desktop pode executar um dentro de si mesmo; o aplicativo web em app.usectrl.dev não pode, porque uma aba de navegador não consegue hospedar um servidor. De qualquer forma, este guia aponta um cliente para um servidor em execução em outro lugar — uma máquina pequena, uma VM na nuvem, um servidor de build.

Pré-requisitos

Um cc_server em execução. Se você não tem um, consulte Executar um servidor headless.
Os três valores de emparelhamento emitidos pelo servidor — a URL do servidor (ws://…/rpc ou wss://…/rpc), um ID do dispositivo e uma chave de emparelhamento — ou um código de convite de uso único fornecido por um administrador do espaço de trabalho. Resgatar um convite provisiona seu usuário, registra sua participação e emite a credencial deste cliente para você, então você nunca precisa lidar com um ID do dispositivo ou uma chave.

Verifique se o servidor está acessível

Um servidor local não precisa de nada: ws://localhost:9030/rpc funciona tanto no desktop quanto no navegador, porque os navegadores tratam o loopback como uma origem confiável.

Um servidor em outra máquina é diferente. app.usectrl.dev é servido por HTTPS, então o navegador só abrirá um socket wss:// com um certificado em que já confie — e o cc_server se recusa desde o início a vincular um endereço que não seja de loopback sem TLS. Forneça a ele uma destas opções:

um certificado diretamente, com --tls-cert e --tls-key
um proxy reverso que termina o TLS na frente, com o servidor iniciado com --insecure (texto simples atrás do proxy, somente em uma rede confiável)
um túnel ou VPN que forneça o certificado — Tailscale, cloudflared ou equivalente. Configurações → Servidor → Conexão e status traz o túnel integrado, com adesão opcional, em Compartilhar este servidor.

Dois ajustes do lado do servidor passam fácil despercebidos. Atrás de um proxy, NAT ou túnel, defina --public-url como o endereço que os clientes devem realmente acessar — por padrão ele usa a vinculação local, então sem isso os clientes tentam o host errado. E se você hospeda sua própria cópia da build web, adicione a origem dela a --allowed-origins, que por padrão contém apenas https://app.usectrl.dev; clientes de loopback e nativos são sempre permitidos.

Conectar o aplicativo de desktop

Em uma instalação nova:

Inicie o Control Center. A tela de primeira execução pergunta Como o Control Center deve ser executado?
Em vez de Executar neste aplicativo, preencha os campos de conexão: a URL do servidor, mais um código de convite ou um ID do dispositivo e uma chave de emparelhamento.
Clique em Conectar. O Control Center se conecta ao servidor e chega à caixa de entrada do espaço de trabalho.

Em um desktop que já executa o próprio servidor:

Abra Configurações → Servidor → Conexão e status.
Clique em Adicionar servidor. Informe a URL do servidor (wss://host:9030/rpc) e um código de convite ou um ID do dispositivo e uma chave de emparelhamento. O botão de sufixo do campo de URL descobre instâncias de cc_server na sua LAN ou tailnet.
Clique em Conectar e depois em Alternar na linha do novo servidor.

A alternância é ao vivo: o aplicativo se reconstrói em torno da nova sessão no mesmo lugar, sem reiniciar. Se a conexão falhar, você permanece no servidor atual e vê o erro. A linha do servidor em que você está não tem a ação Alternar; o servidor local é a primeira linha, rotulada Executar neste aplicativo.

Depois de alternar, o desktop não detém nenhum banco de dados. Todas as telas leem e gravam por meio do servidor remoto, por uma conexão WebSocket.

Conectar o cliente web

A build web é sempre remota.

Abra app.usectrl.dev, ou sua própria cópia da build web.
Informe a URL do servidor, mais um código de convite ou um ID do dispositivo e uma chave de emparelhamento.
O cliente se conecta ao servidor e renderiza a mesma interface que o desktop.

Se houver um link direto de emparelhamento na URL, os campos já vêm preenchidos. A chave de emparelhamento viaja no fragmento da URL, que os navegadores nunca enviam ao servidor que hospeda a página, então o host estático nunca a vê.

O que o navegador não faz

O cliente web lê e grava no mesmo servidor que o desktop, mas algumas superfícies precisam de uma janela nativa ou dos próprios dispositivos da máquina:

sem notificações pop-up do sistema operacional, sons de notificação nem faixa de banners ambiente (a central de notificações no aplicativo continua funcionando)
sem descoberta de servidores na LAN ou tailnet na caixa de diálogo Adicionar servidor
sem leitor de artigos no aplicativo — os artigos do feed de notícias abrem em uma nova aba
sem refazer um resumo de reunião e sem cancelar um que está sendo processado

Dois se comportam de forma diferente em vez de estarem ausentes. A gravação de reuniões funciona no navegador, capturando seu microfone e um compartilhamento de tela que inclui uma faixa de áudio. Abrir no IDE também funciona, mas pede ao servidor que inicie o editor na tela do servidor, então o botão se oculta diante de um host headless sem editores instalados.

Solução de problemas

A conexão expira: o servidor precisa estar acessível a partir do cliente. Verifique a vinculação (--bind any), se a porta está aberta e se --public-url indica o endereço que o cliente consegue realmente acessar. Na internet aberta, o TLS é obrigatório — uma vinculação em texto simples fora do loopback é recusada na inicialização, a menos que o servidor tenha sido iniciado com --insecure atrás de um proxy.
O navegador se recusa a conectar, mas um cliente nativo funciona: a origem do navegador não está na lista --allowed-origins do servidor. O padrão permite apenas https://app.usectrl.dev (além do loopback).
Chave de emparelhamento rejeitada: execute cc_server pair novamente no servidor para rotacionar a chave desse dispositivo e informe a nova. Um dispositivo revogado descobre que sua credencial sumiu e falha de forma segura; a revogação derruba uma sessão ativa em segundos.
Espaço de trabalho errado: o espaço de trabalho faz parte da URL (/workspaces/:workspaceId/…) e acompanha todas as chamadas, então trocar de espaço de trabalho em um cliente altera apenas a sua própria visão. Você só consegue acessar espaços de trabalho dos quais é membro — qualquer outro é recusado com “Not a member of this workspace”. Consulte Espaços de trabalho e isolamento.

Guias relacionados

Executar um servidor headless
Emparelhar um dispositivo: o caminho do relay para o telefone