Gateway
Que Es el Gateway?
El Gateway es el corazon de Neotask -- un unico servicio de larga ejecucion que gestiona todas las sesiones de agentes, canales de mensajeria, ejecucion de herramientas y conexiones de dispositivos. Todo fluye a traves del Gateway.
Es un servidor WebSocket que escucha conexiones de clientes (aplicacion de escritorio, aplicaciones moviles, panel web) y gestiona todo el ciclo de vida del asistente de IA.
Arquitectura
Componentes
- Servidor WebSocket -- Acepta conexiones de clientes (puerto por defecto 18789)
- Servidor HTTP -- Sirve la UI de Control, host del canvas y endpoints de salud
- Adaptadores de Canal -- Mantienen conexiones a plataformas de mensajeria (WhatsApp, Telegram, Discord, etc.)
- Gestor de Sesiones -- Persiste y gestiona el estado de conversacion de agentes
- Programador Cron -- Ejecuta trabajos programados y activaciones de latido
- Runtime de Plugins -- Carga y gestiona el ciclo de vida de plugins
- Servicio de Navegador -- Controla instancias de Chromium para automatizacion web
Modos de Vinculacion
| Modo | Descripcion |
|---|---|
| Loopback | Por defecto. Solo accesible desde localhost (127.0.0.1) |
| LAN | Accesible en su red local. Auto-descubrible via Bonjour/mDNS |
| Tailnet | Accesible a traves de VPN Tailscale con MagicDNS |
| Custom | Vincular a una direccion especifica |
Autenticacion
| Metodo | Descripcion |
|---|---|
| Token | Token bearer de WebSocket (UUID o cadena personalizada) |
| Password | Autenticacion basada en contrasena (hash bcrypt) |
| Trusted Proxy | Para proxies inversos con headers pre-autenticados |
| Local Trust | Conexiones loopback aprobadas automaticamente |
Configuracion
El Gateway se configura via neotask.json (formato JSON5). Secciones clave:
| Seccion | Controla |
|---|---|
agents |
Lista de agentes, valores por defecto, espacios de trabajo |
gateway |
Puerto, modo de vinculacion, autenticacion, comportamiento de recarga |
channels |
Configuracion por canal y credenciales |
tools |
Permisos de herramientas, perfiles, seguridad |
plugins |
Carga de plugins, habilitacion, configuracion por plugin |
models |
Autenticacion de proveedores, respaldos, ajustes de proveedores |
skills |
Directorios de skills, configuracion por skill |
browser |
Perfiles de navegador, puertos, modo headless |
cron |
Configuracion del programador |
session |
Reglas de reinicio, umbrales de compactacion |
messages |
Ajustes de TTS, politicas de media |
memory |
Configuracion de indexacion de memoria |
security |
Sandboxing, modo elevado, aprobaciones |
Recarga en Caliente
Los cambios de configuracion pueden aplicarse sin reiniciar:
| Modo | Comportamiento |
|---|---|
| Hybrid (por defecto) | Aplicar en caliente cambios seguros, reiniciar para otros |
| Hot | Solo aplicar cambios seguros en caliente, ignorar otros |
| Restart | Reiniciar ante cualquier cambio que requiera reinicio |
| Off | Sin recarga automatica |
Acceso Remoto
Tailscale (Recomendado)
Tailscale proporciona acceso remoto seguro y sin configuracion:
- Vincule el Gateway a su Tailnet
- Acceda desde cualquier dispositivo en la misma red Tailscale
- DNS automatico via MagicDNS
- Tailscale Serve puede exponer el panel con HTTPS
Tunel SSH
Reenvie el puerto del Gateway a traves de SSH:
- Simple, seguro, sin cambios de configuracion necesarios
- Funciona con cualquier maquina con capacidad SSH
- Soporta el protocolo WebSocket completo y la UI de Control
Reglas de Seguridad
- Loopback + SSH/Tailscale es la combinacion mas segura
- La vinculacion no loopback requiere configuracion de token de autenticacion
- Fijacion de huella digital TLS disponible para seguridad adicional
- El control del navegador esta deshabilitado para conexiones remotas por defecto
Monitoreo de Salud
Endpoint de Salud
El endpoint HTTP /health retorna:
- Estado del Gateway
- Vivacidad RPC
- Salud por canal (conectado, estado de autenticacion, conteo de cuentas)
- Disponibilidad del navegador
- Agentes activos y nodos conectados
- Tiempo de actividad
Sondeos
- Vivacidad RPC -- Conexion WebSocket + prueba de eco
- Salud del canal -- Verificacion de autenticacion + ping de API por canal
- Disponibilidad del navegador -- Verificacion de puerto, verificacion de proceso
- Conectividad de nodos -- Marca de tiempo del ultimo latido
Descubrimiento
Bonjour/mDNS
Cuando esta vinculado a LAN, el Gateway se anuncia via DNS multicast:
- Tipo de servicio:
_neotask-gw._tcp - Incluye puerto, transporte, estado TLS e informacion DNS de Tailscale
- Las aplicaciones companion descubren el Gateway automaticamente
Descubrimiento de Area Amplia
Descubra gateways a traves de su red con tiempos de espera configurables. Soporta tanto descubrimiento local Bonjour como DNS de Tailscale.
Multiples Gateways
Puede ejecutar multiples instancias de Gateway en la misma maquina usando perfiles:
- Cada perfil tiene configuracion, espacio de trabajo, sesiones y estado separados
- Puertos diferentes para cada Gateway
- Util para aislamiento (personal vs trabajo) o pruebas
Diagnosticos
Doctor
La herramienta de diagnostico integrada verifica:
- Validez de la configuracion
- Permisos de archivos
- Conectividad de canales
- Estado de autenticacion de modelos
- Compatibilidad de version de Node.js
- Configuraciones incorrectas comunes
Puede corregir automaticamente muchos problemas cuando se le da permiso.
Registro (Logging)
Los logs del Gateway se escriben en archivos JSONL diarios:
- Seguimiento de uso de tokens por completacion
- Logs de eventos de canal
- Registro de errores con contexto estructurado
- Niveles de log configurables