Conectarte a un servidor remoto

Todo cliente es un renderizador sobre un cc_server que es el propietario de los datos. La aplicación de escritorio puede ejecutar uno dentro de sí misma; la aplicación web en app.usectrl.dev no puede, porque una pestaña del navegador no puede alojar un servidor. En cualquier caso, esta guía apunta un cliente a un servidor que se ejecuta en otro lugar: una máquina pequeña, una VM en la nube, un servidor de compilación.

Requisitos previos

Un cc_server en ejecución. Si no tienes uno, consulta Ejecutar un servidor headless.
Los tres valores de emparejamiento que emitió el servidor —la URL del servidor (ws://…/rpc o wss://…/rpc), un id de dispositivo y una clave de emparejamiento— o un código de invitación de un solo uso de un administrador del espacio de trabajo. Canjear una invitación aprovisiona a tu usuario, registra tu pertenencia y emite por ti la credencial de este cliente, así que nunca manejas un id de dispositivo ni una clave.

Asegúrate de que el servidor sea accesible

Un servidor local no necesita nada: ws://localhost:9030/rpc funciona tanto desde el escritorio como desde el navegador, porque los navegadores consideran que loopback es un origen confiable.

Un servidor en otra máquina es distinto. app.usectrl.dev se sirve por HTTPS, así que el navegador solo abrirá un socket wss:// con un certificado en el que ya confíe, y cc_server se niega a enlazar una dirección que no sea de loopback sin TLS desde el principio. Dale una de estas opciones:

un certificado directamente, con --tls-cert y --tls-key
un proxy inverso que termine TLS por delante, con el servidor iniciado con --insecure (texto sin cifrar detrás del proxy, solo en una red de confianza)
un túnel o VPN que aporte el certificado: Tailscale, cloudflared o similares. Ajustes → Servidor → Conexión y estado tiene la opción integrada para activar un túnel dentro de Compartir este servidor.

Dos ajustes del lado del servidor son fáciles de pasar por alto. Detrás de un proxy, NAT o túnel, configura --public-url con la dirección a la que los clientes deben marcar realmente: de forma predeterminada usa el enlace local, así que sin él los clientes intentan el host equivocado. Y si alojas tu propia copia de la versión web, agrega su origen a --allowed-origins, que de forma predeterminada solo incluye https://app.usectrl.dev; los clientes de loopback y nativos siempre están permitidos.

Conectar la aplicación de escritorio

En una instalación nueva:

Inicia Control Center. La pantalla de primera ejecución pregunta ¿Cómo debe ejecutarse Control Center?
En lugar de Ejecutar en esta aplicación, completa los campos de conexión: la URL del servidor y, además, un código de invitación o bien un id de dispositivo y una clave de emparejamiento.
Haz clic en Conectar. Control Center marca al servidor y llega a la bandeja de entrada del espacio de trabajo.

En un escritorio que ya ejecuta su propio servidor:

Abre Ajustes → Servidor → Conexión y estado.
Haz clic en Añadir servidor. Introduce la URL del servidor (wss://host:9030/rpc) y un código de invitación o bien un id de dispositivo y una clave de emparejamiento. El botón del sufijo del campo de URL descubre instancias de cc_server en tu LAN o tailnet.
Haz clic en Conectar y luego en Cambiar en la fila del nuevo servidor.

El cambio es en vivo: la aplicación se reconstruye alrededor de la nueva sesión en el mismo lugar, sin reiniciar. Si la conexión falla, permaneces en el servidor actual y ves el error. La fila del servidor en el que estás no tiene la acción Cambiar; el servidor local es la primera fila, etiquetada Ejecutar en esta aplicación.

Una vez cambiado, el escritorio no es propietario de ninguna base de datos. Cada pantalla lee y escribe a través del servidor remoto por WebSocket.

Conectar el cliente web

La versión web siempre es remota.

Abre app.usectrl.dev o tu propia copia de la versión web.
Introduce la URL del servidor y, además, un código de invitación o bien un id de dispositivo y una clave de emparejamiento.
El cliente marca al servidor y renderiza la misma interfaz que el escritorio.

Si hay un enlace profundo de emparejamiento en la URL, los campos vienen rellenados de antemano. La clave de emparejamiento viaja en el fragmento de la URL, que los navegadores nunca envían al servidor que aloja la página, así que el host estático nunca la ve.

Lo que el navegador no hace

El cliente web lee y escribe en el mismo servidor que el escritorio, pero algunas superficies necesitan una ventana nativa o los propios dispositivos de la máquina:

sin avisos de notificación del sistema operativo, sonidos de notificación ni barra de banners ambiente (el centro de notificaciones de la aplicación sigue funcionando)
sin descubrimiento de servidores en la LAN o el tailnet en el cuadro de diálogo Añadir servidor
sin lector de artículos en la aplicación: los artículos del feed de noticias se abren en una pestaña nueva
no se puede volver a ejecutar un resumen de reunión ni cancelar uno que se está procesando

Dos se comportan de forma distinta en lugar de faltar. La grabación de reuniones funciona en el navegador, capturando tu micrófono más una pantalla compartida que incluye una pista de audio. Abrir en el IDE también funciona, pero pide al servidor que lance el editor en la pantalla del servidor, así que el botón se oculta ante un host headless sin editores instalados.

Solución de problemas

La conexión agota el tiempo de espera: el servidor debe ser accesible desde el cliente. Comprueba el enlace (--bind any), que el puerto esté abierto y que --public-url indique la dirección a la que el cliente realmente puede marcar. Por internet abierto, TLS es obligatorio: un enlace de texto sin cifrar que no sea de loopback se rechaza al inicio, a menos que el servidor se haya iniciado con --insecure detrás de un proxy.
El navegador se niega a conectar pero un cliente nativo sí funciona: el origen del navegador no está en la lista --allowed-origins del servidor. La lista predeterminada solo permite https://app.usectrl.dev (además de loopback).
Se rechaza la clave de emparejamiento: vuelve a ejecutar cc_server pair en el servidor para rotar la clave de ese dispositivo y luego introduce la nueva. Un dispositivo revocado se encuentra con que su credencial desapareció y falla en cerrado; la revocación corta una sesión activa en cuestión de segundos.
Espacio de trabajo equivocado: el espacio de trabajo forma parte de la URL (/workspaces/:workspaceId/…) y viaja con cada llamada, así que cambiar de espacio de trabajo en un cliente solo cambia tu propia vista. Solo puedes llegar a los espacios de trabajo de los que eres miembro; cualquier otra cosa se rechaza con “Not a member of this workspace”. Consulta Espacios de trabajo y aislamiento.

Guías relacionadas

Ejecutar un servidor headless
Emparejar un dispositivo: la ruta de retransmisión del teléfono