# Gateway

## Was ist das Gateway?

Das Gateway ist das Herzstueck von Neotask -- ein einzelner dauerhaft laufender Dienst, der alle Agent-Sessions, Messaging-Kanaele, Tool-Ausfuehrung und Geraeteverbindungen verwaltet. Alles fliesst durch das Gateway.

Es ist ein WebSocket-Server, der auf Verbindungen von Clients (Desktop-App, Mobile-Apps, Web-Dashboard) wartet und den gesamten KI-Assistenten-Lebenszyklus verwaltet.

## Architektur

### Komponenten

- **WebSocket-Server** -- Akzeptiert Client-Verbindungen (Standard-Port 18789)
- **HTTP-Server** -- Stellt die Control-UI, den Canvas-Host und Health-Endpunkte bereit
- **Channel-Adapter** -- Halten Verbindungen zu Messaging-Plattformen aufrecht (WhatsApp, Telegram, Discord usw.)
- **Session-Manager** -- Speichert und verwaltet den Agenten-Konversationsstatus
- **Cron-Scheduler** -- Fuehrt geplante Jobs und Heartbeat-Weckrufe aus
- **Plugin-Runtime** -- Laedt und verwaltet den Plugin-Lebenszyklus
- **Browser-Service** -- Steuert Chromium-Instanzen fuer Web-Automatisierung

### Bindungsmodi

| Modus | Beschreibung |
|------|-------------|
| **Loopback** | Standard. Nur von localhost (127.0.0.1) zugaenglich |
| **LAN** | In Ihrem lokalen Netzwerk zugaenglich. Auto-erkennbar ueber Bonjour/mDNS |
| **Tailnet** | Ueber Tailscale VPN mit MagicDNS zugaenglich |
| **Custom** | An eine bestimmte Adresse binden |

### Authentifizierung

| Methode | Beschreibung |
|--------|-------------|
| **Token** | WebSocket Bearer-Token (UUID oder benutzerdefinierte Zeichenkette) |
| **Password** | Passwortbasierte Auth (bcrypt-gehasht) |
| **Trusted Proxy** | Fuer Reverse-Proxys mit Pre-Auth-Headern |
| **Local Trust** | Loopback-Verbindungen automatisch genehmigt |

## Konfiguration

Das Gateway wird ueber `neotask.json` (JSON5-Format) konfiguriert. Wichtige Abschnitte:

| Abschnitt | Steuert |
|---------|----------|
| `agents` | Agentenliste, Standardwerte, Workspaces |
| `gateway` | Port, Bindungsmodus, Auth, Reload-Verhalten |
| `channels` | Pro-Channel-Konfiguration und Anmeldedaten |
| `tools` | Tool-Berechtigungen, Profile, Sicherheit |
| `plugins` | Plugin-Laden, Aktivierung, Pro-Plugin-Konfiguration |
| `models` | Anbieter-Auth, Fallbacks, Anbietereinstellungen |
| `skills` | Skill-Verzeichnisse, Pro-Skill-Konfiguration |
| `browser` | Browserprofile, Ports, Headless-Modus |
| `cron` | Scheduler-Konfiguration |
| `session` | Reset-Regeln, Komprimierungsschwellen |
| `messages` | TTS-Einstellungen, Medien-Policies |
| `memory` | Speicher-Indizierungskonfiguration |
| `security` | Sandboxing, Elevated-Modus, Genehmigungen |

### Hot Reload

Konfigurationsaenderungen koennen ohne Neustart angewendet werden:

| Modus | Verhalten |
|------|----------|
| **Hybrid** (Standard) | Sichere Aenderungen hot-anwenden, fuer andere neu starten |
| **Hot** | Nur hot-safe Aenderungen anwenden, andere ignorieren |
| **Restart** | Bei jeder reload-erfordernden Aenderung neu starten |
| **Off** | Kein automatisches Reload |

## Remote-Zugriff

### Tailscale (Empfohlen)

Tailscale bietet sicheren, konfigurationsfreien Remote-Zugriff:

- Gateway an Ihr Tailnet binden
- Von jedem Geraet im selben Tailscale-Netzwerk zugreifen
- Automatisches DNS ueber MagicDNS
- Tailscale Serve kann das Dashboard mit HTTPS bereitstellen

### SSH-Tunnel

Gateway-Port ueber SSH weiterleiten:

- Einfach, sicher, keine Konfigurationsaenderungen noetig
- Funktioniert mit jeder SSH-faehigen Maschine
- Unterstuetzt das vollstaendige WebSocket-Protokoll und die Control-UI

### Sicherheitsregeln

- **Loopback + SSH/Tailscale** ist die sicherste Kombination
- Nicht-Loopback-Bindung erfordert Auth-Token-Konfiguration
- TLS-Fingerprint-Pinning fuer zusaetzliche Sicherheit verfuegbar
- Browser-Steuerung ist fuer Remote-Verbindungen standardmaessig deaktiviert

## Health-Monitoring

### Health-Endpunkt

Der `/health` HTTP-Endpunkt gibt zurueck:

- Gateway-Status
- RPC-Verfuegbarkeit
- Pro-Channel-Gesundheit (verbunden, Auth-Status, Kontoanzahl)
- Browser-Bereitschaft
- Aktive Agenten und verbundene Nodes
- Betriebszeit

### Probes

- **RPC-Verfuegbarkeit** -- WebSocket-Verbindung + Echo-Test
- **Channel-Gesundheit** -- Auth-Check + API-Ping pro Channel
- **Browser-Bereitschaft** -- Port-Check, Prozess-Check
- **Node-Konnektivitaet** -- Letzter Heartbeat-Zeitstempel

## Erkennung

### Bonjour/mDNS

Bei LAN-Bindung kuendigt sich das Gateway ueber Multicast-DNS an:

- Service-Typ: `_neotask-gw._tcp`
- Beinhaltet Port, Transport, TLS-Status und Tailscale-DNS-Info
- Begleit-Apps erkennen das Gateway automatisch

### Wide-Area-Erkennung

Gateways in Ihrem Netzwerk mit konfigurierbaren Timeouts erkennen. Unterstuetzt sowohl lokale Bonjour- als auch Tailscale-DNS-Erkennung.

## Mehrere Gateways

Sie koennen mehrere Gateway-Instanzen auf demselben Rechner mit Profilen betreiben:

- Jedes Profil hat separate Konfiguration, Workspace, Sessions und Status
- Verschiedene Ports fuer jedes Gateway
- Nuetzlich fuer Isolation (persoenlich vs. Arbeit) oder Tests

## Diagnose

### Doctor

Das integrierte Diagnosetool prueft:

- Konfigurationsgueltigheit
- Dateiberechtigungen
- Channel-Konnektivitaet
- Modell-Auth-Status
- Node.js-Versionskompatibilitaet
- Haeufige Fehlkonfigurationen

Es kann viele Probleme automatisch beheben, wenn die Berechtigung erteilt wird.

### Protokollierung

Gateway-Logs werden in taegliche JSONL-Dateien geschrieben:

- Pro-Completion-Token-Nutzungsverfolgung
- Channel-Event-Logs
- Fehlerprotokollierung mit strukturiertem Kontext
- Konfigurierbare Log-Levels