Gateway
Cos'è il Gateway?
Il Gateway è il cuore di Neotask, un singolo servizio a lunga esecuzione che gestisce tutte le sessioni degli agenti, i canali di messaggistica, l'esecuzione degli strumenti e le connessioni dei dispositivi. Tutto passa attraverso il Gateway.
È un server WebSocket che ascolta le connessioni dai client (app desktop, app mobili, dashboard web) e gestisce l'intero ciclo di vita dell'assistente AI.
Architettura
Componenti
- WebSocket Server, Accetta le connessioni dei client (porta predefinita 18789)
- HTTP Server, Serve la Control UI, il canvas host e gli endpoint di health
- Channel Adapters, Mantengono le connessioni alle piattaforme di messaggistica (WhatsApp, Telegram, Discord, ecc.)
- Session Manager, Persiste e gestisce lo stato delle conversazioni degli agenti
- Cron Scheduler, Esegue i job pianificati e i risveglio tramite heartbeat
- Plugin Runtime, Carica e gestisce il ciclo di vita dei plugin
- Browser Service, Controlla le istanze Chromium per l'automazione web
Modalità di Binding
| Modalità | Descrizione |
|---|---|
| Loopback | Predefinita. Accessibile solo da localhost (127.0.0.1) |
| LAN | Accessibile sulla rete locale. Auto-scopribile tramite Bonjour/mDNS |
| Tailnet | Accessibile tramite Tailscale VPN con MagicDNS |
| Custom | Lega a un indirizzo specifico |
Autenticazione
| Metodo | Descrizione |
|---|---|
| Token | Bearer token WebSocket (UUID o stringa personalizzata) |
| Password | Autenticazione basata su password (hash bcrypt) |
| Trusted Proxy | Per proxy inversi con header pre-autenticati |
| Local Trust | Connessioni loopback approvate automaticamente |
Configurazione
Il Gateway è configurato tramite neotask.json (formato JSON5). Sezioni principali:
| Sezione | Controlla |
|---|---|
agents |
Elenco agenti, valori predefiniti, workspace |
gateway |
Porta, modalità di binding, autenticazione, comportamento di ricarica |
channels |
Configurazione e credenziali per canale |
tools |
Permessi degli strumenti, profili, sicurezza |
plugins |
Caricamento plugin, abilitazione, configurazione per plugin |
models |
Autenticazione provider, fallback, impostazioni provider |
skills |
Directory delle skill, configurazione per skill |
browser |
Profili browser, porte, modalità headless |
cron |
Configurazione dello scheduler |
session |
Regole di reset, soglie di compattazione |
messages |
Impostazioni TTS, policy media |
memory |
Configurazione dell'indicizzazione della memoria |
security |
Sandboxing, modalità elevata, approvazioni |
Hot Reload
Le modifiche alla configurazione possono essere applicate senza riavvio:
| Modalità | Comportamento |
|---|---|
| Hybrid (predefinita) | Applica immediatamente le modifiche sicure, riavvia per le altre |
| Hot | Applica solo le modifiche hot-safe, ignora le altre |
| Restart | Riavvia per qualsiasi modifica che richiede ricarica |
| Off | Nessun ricaricamento automatico |
Accesso Remoto
Tailscale (Consigliato)
Tailscale fornisce accesso remoto sicuro e zero-config:
- Lega il Gateway al tuo Tailnet
- Accedi da qualsiasi dispositivo sulla stessa rete Tailscale
- DNS automatico tramite MagicDNS
- Tailscale Serve può esporre la dashboard con HTTPS
SSH Tunnel
Inoltra la porta del Gateway tramite SSH:
- Semplice, sicuro, nessuna modifica alla configurazione necessaria
- Funziona con qualsiasi macchina con supporto SSH
- Supporta il protocollo WebSocket completo e la Control UI
Regole di Sicurezza
- Loopback + SSH/Tailscale è la combinazione più sicura
- Il binding non-loopback richiede la configurazione del token di autenticazione
- TLS fingerprint pinning disponibile per sicurezza extra
- Il controllo del browser è disabilitato per le connessioni remote per default
Monitoraggio della Salute
Endpoint di Health
L'endpoint HTTP /health restituisce:
- Stato del Gateway
- Liveness RPC
- Salute per canale (connesso, stato auth, numero di account)
- Disponibilità del browser
- Agenti attivi e nodi connessi
- Uptime
Probe
- RPC liveness, Connessione WebSocket + test echo
- Channel health, Controllo auth + ping API per canale
- Browser readiness, Controllo porta, controllo processo
- Node connectivity, Timestamp dell'ultimo heartbeat
Scoperta
Bonjour/mDNS
Quando legato alla LAN, il Gateway si annuncia tramite DNS multicast:
- Tipo di servizio:
_neotask-gw._tcp - Include porta, trasporto, stato TLS e informazioni DNS Tailscale
- Le app companion scoprono automaticamente il Gateway
Scoperta Wide-Area
Scopri i gateway sulla tua rete con timeout configurabili. Supporta sia Bonjour locale che scoperta DNS Tailscale.
Gateway Multipli
Puoi eseguire più istanze del Gateway sulla stessa macchina usando i profili:
- Ogni profilo ha configurazione, workspace, sessioni e stato separati
- Porte diverse per ogni Gateway
- Utile per l'isolamento (personale vs lavoro) o il testing
Diagnostica
Doctor
Lo strumento di diagnostica integrato controlla:
- Validità della configurazione
- Permessi dei file
- Connettività dei canali
- Stato dell'autenticazione dei modelli
- Compatibilità della versione Node.js
- Configurazioni errate comuni
Può correggere automaticamente molti problemi quando glielo viene permesso.
Logging
I log del Gateway vengono scritti in file JSONL giornalieri:
- Tracciamento dell'utilizzo dei token per completamento
- Log degli eventi dei canali
- Log degli errori con contesto strutturato
- Livelli di log configurabili