# Gateway

## Wat is de Gateway?

De Gateway is het hart van Neotask, een enkele langlopende service die alle agentsessies, berichtkanalen, tooluitvoering en apparaatverbindingen beheert. Alles loopt via de Gateway.

Het is een WebSocket-server die luistert naar verbindingen van clients (desktopapp, mobiele apps, webdashboard) en de volledige levenscyclus van de AI-assistent beheert.

## Architectuur

### Componenten

- **WebSocket-server**, Accepteert clientverbindingen (standaardpoort 18789)
- **HTTP-server**, Bedient de Control UI, canvas-host en gezondheidscontrolepunten
- **Kanaaladapters**, Onderhouden verbindingen met berichtenplatformen (WhatsApp, Telegram, Discord, enz.)
- **Sessiebeheerder**, Bewaart en beheert agentgesprekstoestand
- **Cron-planner**, Voert geplande taken en hartslagwakeups uit
- **Plugin-runtime**, Laadt en beheert de pluginlevenscyclus
- **Browserdienst**, Beheert Chromium-instanties voor webautomatisering

### Bindingsmodi

| Modus | Beschrijving |
|------|-------------|
| **Loopback** | Standaard. Alleen toegankelijk vanaf localhost (127.0.0.1) |
| **LAN** | Toegankelijk op uw lokale netwerk. Automatisch te vinden via Bonjour/mDNS |
| **Tailnet** | Toegankelijk via Tailscale VPN met MagicDNS |
| **Aangepast** | Binden aan een specifiek adres |

### Authenticatie

| Methode | Beschrijving |
|--------|-------------|
| **Token** | WebSocket bearer-token (UUID of aangepaste reeks) |
| **Wachtwoord** | Op wachtwoord gebaseerde authenticatie (bcrypt-gehashd) |
| **Vertrouwde proxy** | Voor reverse proxies met pre-auth-headers |
| **Lokaal vertrouwen** | Loopback-verbindingen automatisch goedgekeurd |

## Configuratie

De Gateway wordt geconfigureerd via `neotask.json` (JSON5-formaat). Belangrijke secties:

| Sectie | Beheert |
|---------|----------|
| `agents` | Agentlijst, standaardinstellingen, werkruimten |
| `gateway` | Poort, bindingsmodus, authenticatie, herlaadgedrag |
| `channels` | Per-kanaalconfiguratie en -inloggegevens |
| `tools` | Toolrechten, profielen, beveiliging |
| `plugins` | Pluginladen, inschakelen, per-pluginconfiguratie |
| `models` | Providerauthenticatie, fallbacks, providerinstellingen |
| `skills` | Vaardighedenmappen, per-vaardigheidsconfigutratie |
| `browser` | Browserprofielen, poorten, headless-modus |
| `cron` | Plannerconfiguratie |
| `session` | Resetregels, compactiedrempels |
| `messages` | TTS-instellingen, mediabeleid |
| `memory` | Geheugensindexeringsconfiguratie |
| `security` | Sandboxing, verhoogde modus, goedkeuringen |

### Warm herladen

Configuratiewijzigingen kunnen worden toegepast zonder opnieuw op te starten:

| Modus | Gedrag |
|------|----------|
| **Hybride** (standaard) | Veilige wijzigingen warm toepassen, voor anderen opnieuw opstarten |
| **Warm** | Alleen warm-veilige wijzigingen toepassen, anderen negeren |
| **Opnieuw opstarten** | Opnieuw opstarten bij elke herlaad-vereiste wijziging |
| **Uit** | Geen automatisch herladen |

## Externe toegang

### Tailscale (aanbevolen)

Tailscale biedt veilige, zero-config externe toegang:

- Koppel de Gateway aan uw Tailnet
- Toegang vanaf elk apparaat op hetzelfde Tailscale-netwerk
- Automatische DNS via MagicDNS
- Tailscale Serve kan het dashboard beschikbaar stellen via HTTPS

### SSH-tunnel

Stuur de Gateway-poort door via SSH:

- Eenvoudig, veilig, geen configuratiewijzigingen nodig
- Werkt met elke SSH-compatibele machine
- Ondersteunt het volledige WebSocket-protocol en de Control UI

### Beveiligingsregels

- **Loopback + SSH/Tailscale** is de veiligste combinatie
- Niet-loopback-binding vereist configuratie van het authenticatietoken
- TLS-vingerafdrukpinning beschikbaar voor extra beveiliging
- Browsercontrole is standaard uitgeschakeld voor externe verbindingen

## Gezondheidsmonitoring

### Gezondheidscontrolepunt

Het `/health` HTTP-controlepunt geeft terug:

- Gatewaystatus
- RPC-levendigheid
- Per-kanaalstatus (verbonden, authenticatiestatus, aantal accounts)
- Browsergereedheid
- Actieve agents en verbonden nodes
- Uptime

### Probes

- **RPC-levendigheid**, WebSocket-verbinding + echoptest
- **Kanaalstatus**, Authenticatiecontrole + API-ping per kanaal
- **Browsergereedheid**, Poortcontrole, procescontrole
- **Node-connectiviteit**, Tijdstempel van laatste hartslag

## Detectie

### Bonjour/mDNS

Wanneer gebonden aan LAN, adverteert de Gateway zichzelf via multicast DNS:

- Servicetype: `_neotask-gw._tcp`
- Bevat poort, transport, TLS-status en Tailscale DNS-info
- Companion-apps vinden de Gateway automatisch

### Brede detectie

Ontdek gateways over uw netwerk met configureerbare time-outs. Ondersteunt zowel lokale Bonjour als Tailscale DNS-detectie.

## Meerdere gateways

U kunt meerdere Gateway-instanties op dezelfde machine uitvoeren met behulp van profielen:

- Elk profiel heeft afzonderlijke configuratie, werkruimte, sessies en toestand
- Verschillende poorten voor elke Gateway
- Handig voor isolatie (persoonlijk versus werk) of testen

## Diagnostiek

### Doctor

Het ingebouwde diagnostische hulpmiddel controleert:

- Configuratiegeldigheid
- Bestandsrechten
- Kanaalconnectiviteit
- Modelauthenticatiestatus
- Compatibiliteit met Node.js-versie
- Veelvoorkomende verkeerde configuraties

Het kan automatisch veel problemen oplossen wanneer toestemming wordt gegeven.

### Logboekregistratie

Gateway-logboeken worden geschreven naar dagelijkse JSONL-bestanden:

- Tokengebruiksbijhouding per voltooiing
- Kanaalevenementlogboeken
- Foutlogboekregistratie met gestructureerde context
- Configureerbare logboekniveaus