Gateway
O Que E o Gateway?
O Gateway e o coracao do Neotask -- um unico servico de longa execucao que gerencia todas as sessoes de agente, canais de mensagens, execucao de ferramentas e conexoes de dispositivos. Tudo flui atraves do Gateway.
E um servidor WebSocket que escuta conexoes de clientes (app desktop, apps moveis, dashboard web) e gerencia todo o ciclo de vida do assistente de IA.
Arquitetura
Componentes
- Servidor WebSocket -- Aceita conexoes de clientes (porta padrao 18789)
- Servidor HTTP -- Serve a UI de Controle, host do canvas e endpoints de saude
- Adaptadores de Canal -- Mantem conexoes com plataformas de mensagens (WhatsApp, Telegram, Discord, etc.)
- Gerenciador de Sessoes -- Persiste e gerencia o estado de conversa dos agentes
- Agendador Cron -- Executa jobs agendados e despertares por heartbeat
- Runtime de Plugins -- Carrega e gerencia o ciclo de vida de plugins
- Servico de Navegador -- Controla instancias Chromium para automacao web
Modos de Vinculacao
| Modo | Descricao |
|---|---|
| Loopback | Padrao. Acessivel apenas do localhost (127.0.0.1) |
| LAN | Acessivel na sua rede local. Descoberta automatica via Bonjour/mDNS |
| Tailnet | Acessivel atraves de VPN Tailscale com MagicDNS |
| Personalizado | Vincule a um endereco especifico |
Autenticacao
| Metodo | Descricao |
|---|---|
| Token | Token bearer WebSocket (UUID ou string personalizada) |
| Senha | Autenticacao baseada em senha (hash bcrypt) |
| Proxy Confiavel | Para proxies reversos com headers pre-autenticados |
| Confianca Local | Conexoes loopback auto-aprovadas |
Configuracao
O Gateway e configurado via neotask.json (formato JSON5). Secoes principais:
| Secao | Controla |
|---|---|
agents |
Lista de agentes, padroes, workspaces |
gateway |
Porta, modo de vinculacao, autenticacao, comportamento de reload |
channels |
Configuracao por canal e credenciais |
tools |
Permissoes de ferramentas, perfis, seguranca |
plugins |
Carregamento de plugins, habilitacao, configuracao por plugin |
models |
Autenticacao de provedores, fallbacks, configuracoes de provedores |
skills |
Diretorios de skills, configuracao por skill |
browser |
Perfis de navegador, portas, modo headless |
cron |
Configuracao do agendador |
session |
Regras de reset, limiares de compactacao |
messages |
Configuracoes TTS, politicas de midia |
memory |
Configuracao de indexacao de memoria |
security |
Sandboxing, modo elevado, aprovacoes |
Hot Reload
Mudancas de configuracao podem ser aplicadas sem reiniciar:
| Modo | Comportamento |
|---|---|
| Hibrido (padrao) | Aplica mudancas seguras a quente, reinicia para outras |
| Hot | Aplica apenas mudancas seguras a quente, ignora outras |
| Reiniciar | Reinicia em qualquer mudanca que requer reload |
| Desligado | Sem reload automatico |
Acesso Remoto
Tailscale (Recomendado)
Tailscale fornece acesso remoto seguro, sem configuracao:
- Vincule o Gateway ao seu Tailnet
- Acesse de qualquer dispositivo na mesma rede Tailscale
- DNS automatico via MagicDNS
- Tailscale Serve pode expor o dashboard com HTTPS
Tunel SSH
Encaminhe a porta do Gateway atraves de SSH:
- Simples, seguro, sem mudancas de configuracao necessarias
- Funciona com qualquer maquina capaz de SSH
- Suporta o protocolo WebSocket completo e a UI de Controle
Regras de Seguranca
- Loopback + SSH/Tailscale e a combinacao mais segura
- Vinculacao nao-loopback requer configuracao de token de autenticacao
- Fixacao de fingerprint TLS disponivel para seguranca adicional
- Controle de navegador e desabilitado para conexoes remotas por padrao
Monitoramento de Saude
Endpoint de Saude
O endpoint HTTP /health retorna:
- Status do Gateway
- Liveness RPC
- Saude por canal (conectado, status de autenticacao, contagem de contas)
- Prontidao do navegador
- Agentes ativos e nodes conectados
- Uptime
Probes
- Liveness RPC -- Conexao WebSocket + teste de eco
- Saude do canal -- Verificacao de autenticacao + ping de API por canal
- Prontidao do navegador -- Verificacao de porta, verificacao de processo
- Conectividade do node -- Timestamp do ultimo heartbeat
Descoberta
Bonjour/mDNS
Quando vinculado a LAN, o Gateway se anuncia via DNS multicast:
- Tipo de servico:
_neotask-gw._tcp - Inclui porta, transporte, status TLS e info DNS do Tailscale
- Apps companion descobrem o Gateway automaticamente
Descoberta de Area Ampla
Descubra gateways pela sua rede com timeouts configuraveis. Suporta tanto Bonjour local quanto descoberta DNS do Tailscale.
Multiplos Gateways
Voce pode executar multiplas instancias de Gateway na mesma maquina usando perfis:
- Cada perfil tem configuracao, workspace, sessoes e estado separados
- Portas diferentes para cada Gateway
- Util para isolamento (pessoal vs trabalho) ou testes
Diagnosticos
Doctor
A ferramenta de diagnostico integrada verifica:
- Validade da configuracao
- Permissoes de arquivo
- Conectividade de canais
- Status de autenticacao de modelos
- Compatibilidade de versao do Node.js
- Configuracoes incorretas comuns
Pode corrigir automaticamente muitos problemas quando dada permissao.
Logging
Logs do Gateway sao escritos em arquivos JSONL diarios:
- Rastreamento de uso de tokens por completion
- Logs de eventos de canal
- Log de erros com contexto estruturado
- Niveis de log configuraveis