# Zielarchitektur des neuen KI-Hosts

## Grundsatz

Der Host läuft auf Debian 13. Das Betriebssystem darf im Universitätsnetz
administrierbar bleiben; die KI-Plattform wird ausschließlich an die
WireGuard-Adresse gebunden. KI-Container erreichen Heimnetz und Internet über
den Heim-WireGuard-Peer. Bei Tunnelausfall verhindert eine Blackhole-Route den
unbeabsichtigten Rückfall auf das Universitätsgateway.

```text
Heimnetz / VPN-Clients
        |
     WireGuard
        |
  10.77.0.2:8080     Open WebUI
  10.77.0.2:8081     Profile Router API
        |
   Docker-intern
        +-- Profile Controller -- Docker Socket (feste Allowlist)
        +-- llama-fast         --\
        +-- llama-medium         > exakt einer aktiv
        +-- llama-long         --/
        +-- llama-experimental
        +-- SearXNG + Web-MCP
```

## Container und Vertrauensgrenzen

| Komponente | Außen erreichbar | Aufgabe |
|---|---|---|
| Open WebUI | nur WireGuard, Port 8080 | Chat-Oberfläche |
| Profile Router | nur WireGuard, Port 8081 | OpenAI-API und Profilwahl |
| Profile Controller | nein | startet ausschließlich vier bekannte Profile |
| llama.cpp Profile | nein | Inferenz, Tool Calling, integrierte Vision |
| SearXNG | nein | Websuche für den lokalen Web-MCP |

Nur der Profile Controller erhält den Docker-Socket. Der Router erhält weder
Socket noch Shell-Zugriff und kann dem Controller nur `fast`, `medium`, `long`
oder `experimental` übergeben. Die llama-Container laufen ohne UI,
Capabilities und Schreibzugriff auf die Modelldateien.

## Profilprinzip

Alle Profile verwenden dasselbe selbst gebaute llama.cpp-Image. Separate,
normalerweise gestoppte Containerdefinitionen halten Parameter wie Kontext,
MTP und CPU-Offload reproduzierbar. Ein Wechsel stoppt das alte Profil und
startet genau einen bereits angelegten Container. Dadurch lassen sich Profile
einzeln verändern oder duplizieren, ohne vier Modelle parallel im VRAM zu
halten.

| Profil | Ausgangswert | Zweck |
|---|---:|---|
| fast | 76.800 Kontext, MTP | mindestens ungefähr 80 Token/s anstreben |
| medium | 94.208 Kontext | mehr Kontext ohne CPU-FFN-Offload |
| long | 131.072 Kontext | maximale Nutzbarkeit, CPU-Offload erlaubt |
| experimental | 76.800 Kontext | isolierte Tests ohne Produktion zu ändern |

Diese Werte sind reproduzierbare Startwerte, keine Garantie. Nach Einbau der
RTX 3060 werden sie auf dem Zielhost erneut gemessen. Die zweite Karte wird
nicht automatisch in die Produktionsprofile aufgenommen.

## Netzwerk

- Docker-Netze liegen ausschließlich unter `172.30.0.0/16`.
- Open WebUI und Router binden an `AI_BIND_ADDRESS`, die WireGuard-IP.
- Quellrouting schickt KI-Container in Tabelle 51820 über WireGuard.
- Eine Blackhole-Default-Route bleibt als Fail-Closed-Fallback bestehen.
- Firewallregeln gestatten aus dem VPN nur die beiden veröffentlichten Ports.
- Der Host routet weder Universitätsverkehr ins Heimnetz noch Heimverkehr ins
  Universitätsnetz.
- Das Heimnetz muss die Rückroute zur WireGuard-Adresse kennen. Soll auch der
  Internetzugang der KI über zuhause laufen, braucht der Heim-Peer zusätzlich
  IP-Forwarding und NAT ins Heim-WAN.

## Nicht automatisch installiert

Bildgenerierung, Whisper, TTS sowie Home-Assistant-, ARR- und Unraid-MCPs sind
Erweiterungen. Sie benötigen eigene Modelle, Rechte oder Secrets und bleiben
im sauberen Basissystem deaktiviert. Multimodale Bildanalyse erfolgt direkt
über Qwen plus Projektor. Nicht installierte Worker-Endpunkte antworten klar
  mit `feature_disabled`, statt alte systemd-Pfade aufzurufen.