Zero Connect: conectar Ágora sin abrir puertos | Documentación Connect Manager

Instala Zero Connect y publica la API de Ágora (puerto 8984) en HTTPS sin abrir puertos: alta, URL de API, actualizaciones automáticas y errores.

Zero Connect es el cliente de túnel de Connect Manager para Windows. Se instala en el equipo donde está Ágora y publica su API (puerto 8984) en una dirección HTTPS del tipo https://{subdominio}.connectmanager.live, sin abrir puertos en el router ni montar una VPN. Este manual es para el técnico de FOS o del distribuidor que lo instala: qué datos pedir, cómo se configura, cómo se actualiza y qué hacer cuando no conecta.

Qué hace la integración#

Abre desde el equipo de Ágora una conexión saliente y cifrada con el servidor de túneles de Connect Manager y la mantiene abierta. Por ella bajan las peticiones que llegan a la URL pública.
Publica el puerto local de Ágora (por defecto 127.0.0.1:8984) en https://{subdominio}.{dominio del servidor}, normalmente https://{subdominio}.connectmanager.live. Esa es la URL de la API que se pone en Connect Manager.
Descarga sola su configuración (servidor asignado, credenciales del túnel y subdominios del cliente) desde el hub con un usuario y una clave de acceso: el técnico no teclea direcciones ni tokens del servidor.
Se instala como servicio de Windows (ZeroConnectSvc, «Connect Manager Zero Connect») con arranque automático: funciona aunque nadie inicie sesión en el equipo.
Un segundo servicio, «Connect Manager Zero Connect Updater», vigila el túnel cada 60 segundos (lo arranca si está parado y, tras tres fallos seguidos, lo vuelve a registrar) y busca actualizaciones cada 4 horas.
Comprueba cada 30 segundos que el puerto local responde y avisa al hub cada 30 minutos de los subdominios que tiene activos, para que el panel los vea en línea.
Permite túneles adicionales hacia otros puertos o equipos de la red: HTTP y HTTPS siempre, y TCP, UDP o STCP si el cliente tiene el acceso remoto activado, hasta el máximo de túneles de su plan.
Opcional, si FOS lo activa para el cliente: deja en la carpeta custom-queries de Ágora los informes XML asignados y envía un inventario de hardware y software del equipo con métricas de CPU, RAM y disco.

Qué no hace#

No sustituye a la seguridad de Ágora: cada llamada a la API sigue necesitando el Api-Token de Ágora. Zero Connect solo transporta el tráfico.
No da de alta el cliente ni el subdominio: el usuario y la clave los crea FOS en el hub. El distribuidor ve sus túneles en su portal, pero no puede crearlos ni cambiarlos.
El túnel principal apunta siempre a 127.0.0.1: Zero Connect tiene que ir en el mismo equipo que sirve la API de Ágora. Para llegar a otro equipo de la red hay que usar un túnel adicional.
No hace falta si la API de Ágora ya es accesible desde Internet (por ejemplo, un ACMS alojado en la nube de Ágora).

Requisitos#

Windows de 64 bits con .NET Framework 4.7.2 o superior, en el equipo que sirve la API de Ágora: el servidor de Ágora del local o el servidor del ACMS si el grupo lo tiene en su red.
Permisos de administrador: el programa los pide al abrirse porque crea servicios, reglas del Firewall de Windows y exclusiones de Windows Defender.
API de Ágora activa: licencia del Módulo de Servicios de Integración y, en Herramientas → Activar Módulos Adicionales, el servicio de integración con su Api-Token. Por defecto escucha en el puerto 8984.
Salida a Internet: HTTPS hacia hub.connectmanager.es (configuración y actualizaciones) y TCP hacia el servidor de túneles asignado. No hay que abrir ningún puerto de entrada. Si el firewall corporativo filtra también la salida, pide a FOS el destino y el puerto del servidor de túneles del cliente.
Antivirus: el instalador añade exclusiones en Windows Defender para C:\ConnectManager\ZeroConnect y ZeroConnect.exe. Con otro antivirus, añádelas tú: el motor del túnel es una compilación de FRP y hay antivirus que lo bloquean.
Quién hace qué: FOS da de alta el cliente de Zero Connect en el hub (usuario, clave, servidor, subdominios y límites) y lo activa o desactiva. El técnico (FOS o distribuidor) instala el programa en el equipo de Ágora y pone la URL en Connect Manager. El cliente facilita el acceso de administrador y la salida a Internet.

Datos que necesitamos#

Dato	Quién lo facilita / dónde se saca	Ejemplo o formato	Obligatorio
Usuario del cliente de Zero Connect	FOS, campo Usuario (slug) del cliente en el hub	`restaurante-demo`	Sí
Clave de acceso	FOS, campo Contraseña FRP; se copia del botón de la llave (Credenciales → «Token / Contraseña»). Por canal privado	Cadena alfanumérica	Sí
Subdominio	Se acuerda con FOS; puede estar ya reservado en el cliente o escribirse en el asistente	`restaurante-demo` → `https://restaurante-demo.connectmanager.live`	Sí
Puerto de la API de Ágora	Servidor de Ágora (módulo de servicios de integración)	`8984`	Sí (por defecto)
Api-Token de Ágora	Ágora, Herramientas → Activar Módulos Adicionales. Lo necesitan las integraciones, no el túnel	`TU_API_TOKEN`	Sí
Usuario administrador de Windows	Cliente o distribuidor	—	Sí
Destino y puerto del servidor de túneles	FOS, solo si el cliente filtra la salida a Internet	—	No

Configuración paso a paso#

En el hub (lo hace FOS)#

Entra en /admin → ZeroTunnel → Clientes de Túneles y pulsa Nuevo cliente.
Pestaña Principal / Acceso:
- Estado de cuenta: Activo.
- Kill Switch (Forzar desconexión): apagado. Encendido, el cliente se desconecta y no puede volver a conectar.
- Expira el: vacío es sin caducidad. Con fecha, a partir de ese día se rechaza la conexión.
- Distribuidor: el del cliente. Es lo que hace que el distribuidor vea los túneles en su portal.
- Nombre comercial, Servidor FRP (los marcados [legacy] no tienen control en tiempo real), Usuario (slug) (letras, números, guiones, puntos y @) y Contraseña FRP (botón Generar).
Pestaña Subdominios → + Añadir subdominio: tipo Subdominio, el nombre y Principal activado. Los que se dan de alta aquí quedan reservados para este cliente; los marcados como Principal son los que el asistente de Zero Connect ofrece en la lista.
Pestaña Plan y límites: Máx. túneles simultáneos (túneles distintos abiertos a la vez entre todos los equipos que usen este usuario), Ancho de banda (vacío es sin límite; por ejemplo 10MB), Forzar cifrado, Forzar compresión y Acceso remoto (RDP/VNC), necesario para túneles TCP, UDP o STCP y para los que acaban en _rdp, _vnc o _ssh.
Pestaña Funcionalidades (opcional): Informes Agora XML (Sincronización activada, Intervalo de polling, Informes específicos) e Inventario y telemetría.
Guarda. En el listado, el botón de la llave (Credenciales) muestra Usuario (slug) y Token / Contraseña para pasárselos al técnico.

En el equipo de Ágora#

Comprueba antes que la API responde en local. En el propio equipo, abre en el navegador http://127.0.0.1:8984/api/export-master/?filter=Series. Si contesta algo, aunque sea un error por no llevar el Api-Token, la API está viva. Si el navegador no puede conectar, Ágora no escucha en ese puerto: arréglalo antes de seguir.
Ejecuta CM Zero Connect.exe (pide permisos de administrador). La primera vez pregunta «¿Desea instalar Connect Manager Zero Connect en el sistema?»: responde Sí. Copia el programa a C:\ConnectManager, crea los accesos directos «Connect Manager Zero Connect», lo registra en Programas y características, instala el servicio de actualización y se vuelve a abrir desde su sitio. Si ya estaba instalado y lo ejecutas desde otra carpeta, Sí abre la versión instalada, No reinstala y Cancelar sale.
En la ventana principal pulsa Instalar / Configurar. La primera vez hay que marcar «He leído y acepto los Términos y Condiciones de Uso.» y pulsar Aceptar e Instalar.
Paso 1, Conectar a Zero Connect: escribe Usuario y Clave de acceso y pulsa Conectar →. El programa pide al hub la configuración del cliente; si algo no vale, el error sale debajo.
Paso 2, Configura tu túnel:
- Servidor asignado: informativo, lo decide FOS.
- Subdominio: elige uno de la lista (los reservados para el cliente) o escribe uno nuevo, solo con letras, números y guiones. Debajo se ve cómo quedará la URL: → https://{subdominio}.connectmanager.live.
- Nombre del servicio: propone el nombre del equipo. El túnel se identifica por usuario y subdominio, así que puedes dejarlo.
- Puerto local: 8984. Cámbialo solo si la API de Ágora del cliente escucha en otro.
Pulsa Instalar ✓.
El programa guarda la configuración cifrada, crea las reglas del Firewall y las exclusiones de Defender, instala el servicio y lo arranca. En la tarjeta Estado del túnel tiene que salir Servicio en ejecución en verde, con Servidor, URL acceso (botón Copiar), IP local y Puerto local.

[!NOTE] Si en el paso 2 aparece «⚠ Servidor legacy: el túnel funciona, pero no habrá kill switch en tiempo real ni métricas», es solo un aviso sobre el servidor asignado. El túnel funciona igual.

En Connect Manager#

En Connect Manager App (app.connectmanager.es) → Administración → Locales → el local: pega la URL acceso de Zero Connect en la URL de la API de Ágora, sin :8984 (el túnel ya lleva a ese puerto), y pon el Api-Token de Ágora en la API key. Guarda.
Si el local usa módulos del hub: /admin → Seguridad → Locales → el local → Datos de Conexión con ágora → Local: URL de la API y Local: API Token (o los campos de ACMS si está marcado ¿Utiliza arquitectura ACMS?).

Túneles adicionales, cambios y desinstalación#

Servicio → Túneles adicionales... (o el botón ⊕ Túneles adicionales) abre una tabla con Tipo, Nombre, Subdominio / Puerto, IP Local y Puerto. En HTTP y HTTPS la tercera columna es un subdominio; en TCP y UDP, el puerto remoto. Guardar y aplicar reinicia el servicio. La cabecera dice cuántos adicionales permite el plan.
Reconfigurar → vuelve a lanzar el asistente: sirve para cambiar de usuario, clave, subdominio o puerto.
El botón de la izquierda cambia según el estado (Iniciar, Detener o Reiniciar). El menú Servicio tiene además Reiniciar Servicio y Actualizar; el menú Ayuda, Log y Log del updater.
Cerrar la ventana no corta el túnel: lo mantiene el servicio.

[!WARNING] Servicio → Desinstalar Servicio (y la desinstalación desde Programas y características) quita Zero Connect entero y, al terminar, borra la carpeta C:\ConnectManager completa, con lo que haya dentro de otras aplicaciones de Connect Manager. Si el servidor tiene también Connect Manager IA (C:\ConnectManager\MCP), guarda antes su fichero identidad.json: al reinstalarlo con ese fichero en su sitio conserva su dirección; sin él, la dirección cambia y hay que volver a añadir el conector en cada asistente.

Cómo funciona#

Al instalar, Zero Connect pide su configuración al hub enviando el usuario en la ruta y la clave en la cabecera X-Client-Token. Con lo que recibe abre una conexión cifrada con el servidor de túneles y se identifica con el usuario y la clave. El servidor consulta al hub si el cliente existe y está activo, si el Kill Switch está apagado, si no está bloqueado ni caducado y si la clave es correcta. Después Zero Connect publica su subdominio y el hub vuelve a comprobar: que el subdominio no esté bloqueado ni reservado para otro cliente y que no se supere el máximo de túneles. A partir de ahí, cuando una integración llama a la URL pública, el servidor baja la petición por el túnel ya abierto, Zero Connect la entrega en el puerto 8984 del propio equipo y devuelve la respuesta por el mismo camino.

sequenceDiagram
    participant ZC as Zero Connect
    participant HUB as Hub Connect Manager
    participant SRV as Servidor de túneles
    participant CM as Integración
    participant AG as API de Ágora
    ZC->>HUB: Pide su configuración con usuario y clave
    HUB-->>ZC: Servidor asignado, credenciales y subdominios
    ZC->>SRV: Conexión saliente cifrada y login
    SRV->>HUB: Comprueba cliente, estado y clave
    HUB-->>SRV: Aceptado
    ZC->>SRV: Publica el subdominio
    SRV->>HUB: Comprueba límite y subdominio
    HUB-->>SRV: Aceptado
    CM->>SRV: Petición HTTPS a la URL del subdominio
    SRV->>ZC: Reenvía la petición por el túnel
    ZC->>AG: Petición al puerto 8984 local
    AG-->>ZC: Respuesta de Ágora
    ZC-->>SRV: Respuesta por el túnel
    SRV-->>CM: Respuesta HTTPS

Lo que pasa después, sin que nadie intervenga:

Cortes de red: si la conexión con el servidor se cae después de haber entrado, el túnel se reconecta solo.
Rechazo al conectar: si el servidor rechaza el primer login (clave mal, cliente desactivado…), el motor se cierra en vez de reintentar a ciegas, y el servicio y su vigilante lo vuelven a arrancar. El motivo queda en Ayuda → Log (C:\ConnectManager\ZeroConnect\ZeroConnect.log).
Kill Switch y bloqueos: si FOS desactiva o bloquea al cliente, el servidor corta la sesión en su siguiente comprobación y ya no deja volver a entrar.
Registro del subdominio: la primera vez que se conecta, el subdominio queda dado de alta a nombre del cliente en el hub. Cada 30 minutos el vigilante confirma que sigue en línea.
Informes de Ágora (opcional): cada Intervalo de polling (60 minutos por defecto) compara la huella SHA-256 de cada XML asignado con el de la carpeta custom-queries y solo copia los que han cambiado. La carpeta y una sincronización inmediata están en Servicio → Sincronizar informes Ágora.

[!WARNING] Un informe XML sin el nodo <Columns> impide que arranque el servicio de Ágora del cliente («El nodo Columns es obligatorio»). Revisa cualquier informe antes de asignarlo en /admin → ZeroTunnel → Informes Agora.

Actualizaciones automáticas#

El servicio de actualización pregunta al hub cada 4 horas (la primera vez, dos minutos después de arrancar) si hay una versión nueva, enviando la versión instalada y el usuario del cliente. El hub anota la consulta en /admin → ZeroTunnel → Parque de clientes, que es donde FOS asigna el canal: Estable por defecto o Beta, que recibe la más alta entre la beta y la estable activas. El hub puede además soltar una versión a un porcentaje del parque o forzar una vuelta atrás, que se instala aunque la versión sea anterior. Si hay versión para el cliente, Zero Connect solo la descarga de una dirección HTTPS de connectmanager.es o connectmanager.live, comprueba su huella SHA-256 y que sea más nueva, para el servicio, sustituye el ejecutable y lo vuelve a arrancar. La configuración del túnel no se toca. El hub no ofrece una versión que no tenga huella.

sequenceDiagram
    participant UPD as Updater
    participant HUB as Hub Connect Manager
    participant SVC as Servicio del túnel
    loop Cada 4 horas
        UPD->>HUB: Versión instalada y usuario del cliente
        HUB-->>UPD: Versión de su canal, URL y huella SHA-256
    end
    alt Hay versión nueva para su canal
        UPD->>HUB: Descarga el paquete
        UPD->>UPD: Comprueba dominio, huella y versión
        UPD->>SVC: Para el servicio
        UPD->>UPD: Sustituye el ejecutable
        UPD->>SVC: Lo vuelve a arrancar
    end

Para forzarlo a mano: Servicio → Actualizar. Si hay versión, enseña el número, el tamaño y las novedades y pregunta «¿Desea actualizar ahora?» (las obligatorias y las vueltas atrás no preguntan). Si no, dice «La aplicación está actualizada». El detalle queda en Ayuda → Log del updater (C:\ConnectManager\Updater\updater.log).

Comprobar que funciona#

En Zero Connect: Servicio en ejecución en verde y la dirección en URL acceso.
Desde fuera de la red del local (por ejemplo, un móvil sin wifi), llama a la API con su token: curl -H "Api-Token: TU_API_TOKEN" "https://restaurante-demo.connectmanager.live/api/export-master/?filter=Series". Tiene que devolver las series en JSON. Sin la cabecera, Ágora contesta que falta el token, y eso también demuestra que el túnel llega.
FOS, en /admin → Seguridad → Test de conexión, pulsa Probar en la fila del local: tiene que salir Conecta con la versión de Ágora.
En /admin → ZeroTunnel → Clientes de Túneles el cliente sale Online y se actualiza el último login. El distribuidor lo ve en Portal de distribuidores → Zero Connect → Túneles con el icono de conectado.
Reinicia el equipo de Ágora sin iniciar sesión y repite el paso 2: el túnel tiene que volver solo.
Haz una operación real de la integración que lee Ágora (por ejemplo, un buscador de productos o de habitaciones) para confirmar URL y token en la ficha del local.

Errores frecuentes y solución#

Síntoma	Causa	Solución
Paso 1: «Usuario y clave son obligatorios.»	Falta uno de los dos datos.	Rellena los dos.
Paso 1: «Error: Error al obtener configuración: Cliente no autorizado»	Usuario o clave incorrectos, o el cliente no está Activo o tiene el Kill Switch encendido.	Copia de nuevo los datos desde Credenciales; FOS revisa el estado en Clientes de Túneles.
Paso 1: el error termina en «blocked» o «expired»	Cliente bloqueado temporalmente o con la fecha de Expira el pasada.	FOS lo desbloquea o amplía la fecha.
Paso 1: «Error al obtener configuración» con un error de red	Sin salida HTTPS hacia `hub.connectmanager.es` (proxy o firewall).	Permite la salida al hub por HTTPS.
«El subdominio solo puede contener letras, números y guiones (-).»	Caracteres no válidos (puntos, espacios, ñ).	Usa solo a-z, 0-9 y guiones.
«Error en el servicio» y en rojo «⚠️ El subdominio '…' está reservado para otro cliente.»	El subdominio es de otro cliente.	Reconfigurar → con otro subdominio, o pide a FOS que lo libere.
En rojo «Error: Autenticación fallida» o «Error: Conexión fallida»; en el log, «Token de autenticación incorrecto.»	La clave del cliente ha cambiado (FOS pulsó Regenerar token).	Reconfigurar → con la clave nueva.
En el log: «Servicio desactivado por el administrador.», «Cuenta suspendida. Contacte con soporte.», «El servicio expiró el …» o «Acceso bloqueado temporalmente hasta el …»	FOS ha cortado el servicio a ese cliente.	FOS revisa Kill Switch, Estado de cuenta, Expira el y bloqueos.
En el log: «Límite de túneles alcanzado (N). Cierra uno existente antes de abrir otro.»	Ese usuario tiene ya abiertos todos los túneles de su plan, sumando todos sus equipos.	Quita túneles adicionales o pide a FOS que suba Máx. túneles simultáneos.
En el log: «Error al conectar con servicio local en [127.0.0.1:8984] … Verifique que el puerto no esté en uso o bloqueado.»	La API de Ágora no escucha en ese puerto: servicio de Ágora parado, módulo de servicios de integración sin activar o puerto distinto.	Arranca Ágora o activa el módulo. Si el puerto es otro, Reconfigurar → con el bueno.
«Error: No se conecta al servidor»; el log repite «Error al conectar con el servidor»	No hay salida hacia el servidor de túneles.	Permite la salida TCP; pide a FOS destino y puerto.
«El inicio del servicio tardó demasiado. Comprueba si el antivirus está bloqueando ZeroConnect.exe.»	Antivirus o EDR bloqueando el motor.	Exclusión para `C:\ConnectManager\ZeroConnect` y `ZeroConnect.exe`.
«El servicio no está instalado. Vuelve a instalar Zero Connect.» o «No se encuentra NSSM en: … La instalación puede estar incompleta.»	Instalación incompleta.	Vuelve a pasar por Instalar / Configurar.
«Acceso remoto (STCP/RDP/VNC/SSH) no habilitado para este cliente.»	Túnel adicional de tipo STCP o con nombre acabado en `_rdp`, `_vnc` o `_ssh`.	FOS activa Acceso remoto (RDP/VNC) en Plan y límites.
Test de conexión: «No se llega» con «Conexión rechazada: puerto cerrado o servicio parado.» o «No se resuelve el dominio.»	Túnel caído, servicio parado o URL mal escrita.	Revisa el estado en Zero Connect y copia la URL con el botón Copiar.
Test de conexión: «Token inválido»	El túnel llega, pero el Api-Token de la ficha del local no es el de Ágora.	Corrige el token en la ficha del local.
Test de conexión: «Responde 404 a un endpoint que existe en todas las versiones: la URL probablemente no apunta a la API de Ágora.»	La URL apunta a otro sitio o el túnel no está publicado.	Comprueba que la URL de la ficha es la de URL acceso.

Preguntas frecuentes#

¿Hay que abrir el puerto 8984 en el router para conectar Ágora con Connect Manager?#

No. Con Zero Connect la conexión la abre el equipo de Ágora hacia fuera, así que no hace falta abrir puertos de entrada, ni IP fija, ni VPN. Solo necesita salida a Internet.

¿Qué URL de API pongo en Connect Manager si uso Zero Connect?#

La que muestra Zero Connect en URL acceso, del tipo https://{subdominio}.connectmanager.live, sin :8984. El token sigue siendo el Api-Token de Ágora.

¿Zero Connect se actualiza solo?#

Sí. El servicio de actualización consulta el hub cada 4 horas y aplica la versión de su canal (estable o beta, lo decide FOS) comprobando su huella SHA-256. También se puede lanzar desde Servicio → Actualizar.

¿Qué pasa si se reinicia el servidor de Ágora o se va la luz?#

Los dos servicios arrancan solos con Windows, sin iniciar sesión, y el túnel se reconecta. Si el motor se cae, el vigilante lo vuelve a levantar en menos de un minuto.

¿Puedo usar el mismo usuario de Zero Connect en varios locales?#

Sí, si FOS lo ha preparado así: cada equipo publica su propio subdominio. Todos cuentan para el mismo Máx. túneles simultáneos y se cortan a la vez si se desactiva el cliente.

¿Necesito Zero Connect para Connect Manager IA?#

No. Connect Manager IA trae su propio túnel y su dirección propia. Pueden convivir en el mismo servidor, con cuidado al desinstalar Zero Connect (ver el aviso de desinstalación).

Referencias#

Connect Manager IA: ChatGPT, Claude, Gemini y Copilot con Ágora
Seguridad de red y direcciones IP en Connect Manager
Direcciones IP salientes de Connect Manager (si en vez de Zero Connect se abre el puerto y se filtra por origen)
Glosario de Connect Manager
Proyecto FRP, base del motor del túnel: github.com/fatedier/frp