michael/AI-Profile-Router
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simplify Athena stack and recovery

Browse Source
This commit is contained in:
Mikei386
2026-08-25 22:27:26 +02:00
parent c4851305d1
commit 069da8b4f0
70 changed files with 887 additions and 5806 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
-188
View File
@@ -1,188 +0,0 @@
# Zielarchitektur des neuen KI-Hosts
## Grundsatz
Der Host läuft auf Debian 13. Das Betriebssystem darf im Universitätsnetz
administrierbar bleiben. Ein eigener Docker-Gateway beendet WireGuard und ist
der einzige von außen erreichbare Einstieg in die KI-Plattform. KI-Container
erreichen Heimnetz und Internet über die Fritzbox; Quellrouting zum Gateway
verhindert bei Tunnelausfall einen Rückfall auf das Universitätsgateway.
```text
Heimnetz / VPN-Clients
|
WireGuard
|
<Fritz-VPN-IP>:8080 Open WebUI
<Fritz-VPN-IP>:8081 Profile Router API
<Fritz-VPN-IP>:9119 Hermes Dashboard
<Fritz-VPN-IP>:8642 Hermes Agent API
<Fritz-VPN-IP>:8201-08 direkte MCP-Endpunkte
|
Docker-intern
+-- Profile Controller -- Docker Socket (feste Allowlist)
+-- llama-fast --\
+-- llama-medium > exakt einer aktiv
+-- llama-large --/
+-- llama-uncensored (80K, Abliterated, dual GPU)
+-- llama-experimental
+-- llama-ultra (256K, text-only, dual GPU)
+-- TTS-Gateway
| +-- XTTS-v2 / Annmarie Nele (RTX 3060, primär)
| +-- Piper-TTS (CPU, automatischer Fallback)
+-- internes MCP-Netz
+-- Web-MCP + SearXNG + TinySearch/Crawl4AI + YouTube-Adapter
+-- offizieller GitHub-MCP (drei kleine read-only Werkzeuge)
+-- Home-Assistant-MCP-Relay
+-- ARR-MCP
+-- Unraid-MCP
```
## Container und Vertrauensgrenzen
| Komponente | Außen erreichbar | Aufgabe |
|---|---|---|
| WireGuard Gateway | VPN-Adresse, feste Portmatrix | Tunnel und direkte TCP-Proxys für UI, API und Werkzeuge |
| Open WebUI | nur Docker-intern | Chat-Oberfläche |
| Hermes Agent | nur Docker-intern; Dashboard/API über VPN-Gateway | agentische Oberfläche, Skills, Sitzungen und MCP-Client |
| Profile Router | nur Docker-intern | OpenAI-API und Profilwahl |
| Profile Controller | nein | startet ausschließlich fest erlaubte Profile |
| llama.cpp Profile | nein | Inferenz, Tool Calling, integrierte Vision |
| XTTS-v2 | nein | primäre deutsche/englische Text-to-Speech-Ausgabe auf RTX 3060 |
| TTS-Gateway | nein | serialisiert XTTS, segmentiert Sprachwechsel und fällt auf Piper zurück |
| Piper | nein | CPU-basierte Text-to-Speech-Rückfallebene |
| MCP-Tool-Stack | über feste VPN-Ports | voneinander getrennte Werkzeugbereiche für OpenWebUI, Pi und Hermes |
| SearXNG/TinySearch | nein | private Suche, Crawl4AI-Extraktion und lokales Reranking |
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`, `large`,
`ultra`, `uncensored` 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 mehrere Modelle parallel im VRAM zu
halten.
| Profil | Ausgangswert | Zweck |
|---|---:|---|
| fast | 76.800 Kontext, MTP | mindestens ungefähr 80 Token/s anstreben |
| medium | 160.000 Kontext, Pure, 90:10, MTP3 | Standardprofil |
| large | 192.000 Kontext, Pure, 86:14, MTP3 | große Agenten-/MCP-Sitzungen |
| ultra | 262.144 Kontext, Pure, 80:20, MTP2 | maximaler Textkontext |
| uncensored | 80.000 Kontext, Abliterated Q4_K_M, 90:10, MTP2 | weniger Verweigerungen bei unveränderten Tool-Grenzen |
| experimental | 76.800 Kontext | isolierte Tests ohne Produktion zu ändern |
Diese Matrix wurde auf RTX 5080 und RTX 3060 gemessen und ist bis zu einer
bewussten Neubewertung der verbindliche Produktionsstandard.
Bei Fast, Medium, Large und Uncensored bleibt das Sprachmodell wie in der Tabelle
verteilt, während `MTMD_BACKEND_DEVICE=CUDA1` den vollständigen
Multimodal-Projektor auf die RTX 3060 legt. Ein reproduzierbarer Test mit einem
synthetischen Bild (1024×768, 835 Eingabetoken) senkte die Bild-/Promptzeit im
Medium-Profil von 23,17 auf 1,68 Sekunden und die gesamte Anfrage von 24,96
auf 2,94 Sekunden. Der Projektor belegte dabei rund 1,1 GiB zusätzlichen VRAM
auf der 3060. Das Uncensored-Profil nutzt seinen passenden eigenen Projektor.
Ultra bleibt für maximalen Kontext bewusst text-only.
## Netzwerk
- Docker-Netze liegen ausschließlich unter `172.30.0.0/16`.
- Open WebUI und Router besitzen keine Docker-Host-Portfreigabe.
- Der Gateway lauscht in seinem eigenen Namespace auf der Fritz-VPN-IP und
leitet die dokumentierte Portmatrix zu UI, API, TTS und MCPs weiter.
- Quellrouting schickt `172.30.10.0/24` und `172.30.50.0/24` zum Gateway;
Regeln für `172.30.0.0/16` bewahren rein internen Docker-Verkehr.
- Die verschlüsselten äußeren Gateway-Pakete sind eng von diesen Quellregeln
ausgenommen und verlassen Athena über die normale Standortverbindung.
- Bleibt die Gateway-Adresse aus, existiert keine alternative Route für die
Anwendungscontainer (fail-closed).
- Der Host routet weder Universitätsverkehr ins Heimnetz noch Heimverkehr ins
Universitätsnetz.
- Adressen, Heimrouten, Full-Tunnel und Keepalive stammen aus dem root-only
Fritzbox-Clientexport; der Debian-Host übernimmt dessen Default-Route nicht.
## Optionale Erweiterungen
Open WebUI spricht ausschließlich den Router an. Dieser reicht TTS intern an
das TTS-Gateway weiter. Das Gateway nutzt primär XTTS-v2 mit der Stimme
`Annmarie Nele` auf der RTX 3060. Gemischte deutsch-englische Antworten laufen
bewusst als vollständige deutsche Satzblöcke: Das vermeidet die langen Pausen,
Tonhöhensprünge und unverständlichen Übergänge, die beim Zusammensetzen vieler
kurzer Sprachsegmente entstanden. Vollständig englische Texte werden weiterhin
automatisch mit `language=en` gesprochen. Da der offizielle
XTTS-Streamingserver nur einen Auftrag
gleichzeitig unterstützt, serialisiert das Gateway die Aufträge. Bei Fehler,
Timeout oder belegter Queue übernimmt automatisch Piper auf der CPU. Kein
TTS-Port wird veröffentlicht. Der äußere Kompatibilitätsname bleibt bewusst
`piper/alloy`, damit persistente Open-WebUI-Einstellungen nach Updates und
Restores gültig bleiben. Bildgenerierung und Whisper werden bei Bedarf über
die stabilen Router-Endpunkte gestartet; ihre Worker sind keine dauerhaft
geladenen Inferenzprofile. Home Assistant, ARR, GitHub und Unraid sind vorbereitete
MCP-Profile: Sie werden erst gestartet, wenn die jeweilige root-only
Secret-Datei vorhanden ist. Multimodale Bildanalyse erfolgt direkt über Qwen
plus Projektor. Nicht installierte Worker-Endpunkte antworten klar mit
`feature_disabled`, statt alte systemd-Pfade aufzurufen.
Vor der Synthese wandelt das Gateway visuelle Schreibweisen in natürliche
deutsche Sprache um. Dazu gehören Datumsangaben, Temperaturbereiche,
Prozentwerte, fünfstellige Postleitzahlen und Internet-Domains. Das verhindert
Ausgaben wie „zweiundzwanzig Komma zehn“ für `22° / 10°`; Domain-Endungen
werden eindeutig buchstabiert.
## Zentrale MCP-Werkzeugebene
Werkzeuge werden nicht in llama.cpp eingebaut. Sie laufen als eigene, zentrale
MCP-Container. Open WebUI greift intern darauf zu; Pi, Hermes und andere
Clients verwenden ihre festen Ports direkt auf Athenas WireGuard-Adresse. Ein
zusätzliches MCP-Gateway ist nicht erforderlich. So können alle Oberflächen
dieselben Werkzeuge verwenden, ohne Secrets zu duplizieren.
Die Trenneinheit ist **ein Container pro Fachbereich und Vertrauensstufe** –
nicht ein Container pro einzelner Funktion und nicht ein gemeinsamer
Allzweck-MCP mit sämtlichen Zugangsdaten.
```text
Open WebUI ── internes Netz ───────────┬── native Websuche / TinySearch-MCP
├── platform-context-mcp
├── home-assistant-mcp
├── arr-mcp
├── github-mcp-read
├── navidrome-mcp
└── unraid-mcp-read
Hermes Agent ─ WireGuard ─┐
Pi / weitere MCP-Clients ─┴── feste VPN-Ports 8201-8208 ── MCP-Container
```
| Container | Werkzeugbereich | Standardrecht |
|---|---|---|
| `tinysearch` | allgemeine portable Websuche für beliebige Sites | nur lesen; kurze Resultate |
| `athena-operator` | strukturierte Plattformarbeit plus breites Terminal | Power und Erreichbarkeitsumbau blockiert |
| `platform-context-mcp` | kurze Architekturauskunft, Quellen und Snapshot | strikt read-only, kein Docker-Socket |
| `github-mcp-read` | Repositorysuche, gezielte Datei- und Code-Suche | drei Tools, strikt nur lesen |
| `home-assistant-mcp-read` | Entities, Bereiche, Historie, Diagnose | nur lesen |
| `home-assistant-mcp-write` | kontrollierte HA-Änderungen | Preview/Approval |
| `arr-mcp-read` | Sonarr/Radarr-Status und Releasesuche | nur lesen |
| `arr-mcp-write` | Suche fehlender Episoden über Sonarr-Indexer | Preview/Approval; Monitoring unverändert |
| `navidrome-mcp` | Musikbibliothek, Suche, Playlists, Favoriten, Hörverlauf | eigener Navidrome-Benutzer; gezielt aktivieren |
| `unraid-mcp-read` | System-, Container- und begrenzte Logdiagnose | nur lesen |
| `unraid-mcp-admin` | eng definierte Verwaltungsaktionen | bewusst aktivieren |
| `sandbox-mcp` | temporäre Code- und Dateiarbeit | isolierter Arbeitsraum |
Read- und Write-Instanzen dürfen dasselbe Image verwenden, laufen aber mit
unterschiedlichen Tokens, Netzwerkzugriffen und Werkzeug-Allowlisten. Der
Gateway besitzt keine HA-, ARR- oder Unraid-Secrets. Er authentifiziert Clients,
routet zum zuständigen MCP und begrenzt Antwortgröße, Laufzeit und Aufrufrate.
Ein zweiter allgemeiner Host-Shell-MCP ist ausgeschlossen, weil das breite
Terminal bereits im Athena Operator liegt. Der Operator hält Ausgaben kurz und
blockiert ausschließlich Befehle, die Stromversorgung oder Athenas entfernte
Erreichbarkeit gefährden. Wiederkehrende Administrative Aktionen bleiben als
strukturierte, prüfbare Werkzeuge modelliert.
OpenWebUI ergänzt passende Fachgruppen automatisch; das allgemeine Web bleibt
immer verfügbar. Andere Clients können dieselben MCP-Endpunkte direkt nutzen.
docs/ATHENA_REBUILD_LOG.md
-77
View File
@@ -1,77 +0,0 @@
# Athena-Leerhostaufbau – Praxisprotokoll
> Dieses Dokument ist ein chronologisches Aufbauprotokoll. Darin genannte alte
> Profilnamen und Kontextwerte sind keine aktuelle Konfiguration. Seit dem
> 22. August 2026 gilt `STANDARD_PROFILE_MATRIX.md`.
Dieses Protokoll hält die Abweichungen fest, die beim realen Neuaufbau auf
einem frischen Debian-13-Host sichtbar wurden. Jede dauerhaft notwendige
Korrektur muss zusätzlich im Installer, Restore-Skript oder in der regulären
Betriebsdokumentation umgesetzt werden. Das Protokoll enthält keine Secrets,
Chats oder privaten Nutzdaten.
## Zielsystem
- Hostname: `Athena`
- Betriebssystem: Debian 13 amd64
- Persistente Datenplatte: `/data`, ext4
- Haupt-GPU: NVIDIA RTX 5080 mit 16 GB VRAM
- Containerbetrieb: Docker CE und Compose-Plugin
- Inferenz: gepinnter llama.cpp-Build in Docker
- Oberfläche: OpenWebUI
- Werkzeuge: getrennte MCP-Container für Web, Home Assistant, ARR und Unraid
## Bereits eingearbeitete Korrekturen
| Bereich | Beobachtung im Leerhosttest | Dauerhafte Umsetzung |
|---|---|---|
| NVIDIA | Debian-Basispakete allein lieferten nicht den benötigten aktuellen Treiberzweig. | Offizielles NVIDIA-Repository, Mindestversion, Open-Kernelmodule und reproduzierbarer Neustartpfad im Installer. |
| CUDA | Container fanden einzelne CUDA-Kompatibilitätsbibliotheken nicht zuverlässig. | Bibliothekspfad und `ldconfig` werden vom Installer hergestellt und geprüft. |
| Modelle | Durch die restriktive Installer-Umask konnte der unprivilegierte Inferenzprozess GGUF-Dateien nicht lesen. | Nach erfolgreicher Hashprüfung werden Modelle unveränderlich, aber lesbar mit Modus `0444` gesetzt. |
| MTP | Das Fast-Modell besitzt den verwendeten MTP-Tensor bereits im IQ4-MIX-GGUF. | Kein redundanter Draft-Download und kein falscher separater Startparameter. |
| Router | Frische Volumes und der unmittelbar folgende API-Aufruf führten zu Ownership- beziehungsweise Start-Rennen. | Minimale Dateisystem-Capabilities, eigener Healthcheck, Abhängigkeit von gesundem Controller und explizite Readiness-Prüfung. |
| Installer | Ein erfolgreicher Containerstart wurde zu früh als erfolgreiche Installation gewertet. | Abschluss erst nach Router-Health, erfolgreicher Fast-Aktivierung und eindeutigem `INSTALL_READINESS_OK`-Marker. |
| Websuche | TinySearch/SearXNG wurden in mehreren Pfaden gestartet. | Websuche wird ausschließlich durch den Tool-Stack installiert und gestartet. |
| MCP | Altcontainer sollten nicht in die neue Architektur übernommen werden. | Neue, getrennte Tool-Container; Restore importiert nur freigegebene Secret- und Laufzeitdateien. |
| OpenWebUI | Eine gesicherte Datenbank war neuer als das zunächst gepinnte OpenWebUI-Image. | Datenbank und Image werden versionsgleich wiederhergestellt; Registry-Digest und OCI-Build-Revision werden geprüft. |
| Image-Backup | Das alte Archiv `openwebui-mcp-images.tar.gz` enthielt trotz seines Namens nicht das inventarisierte OpenWebUI-Image. | Restore nutzt als sicheren Fallback nur den gesicherten unveränderlichen Digest. Künftige Backups benötigen einen isolierten Probeimport. |
| Wiederholung | Ein späterer Installerlauf hätte die restaurierte OpenWebUI-Version wieder überschrieben. | Das Restore schreibt den geprüften lokalen Image-Tag auch in die dauerhafte Installationskonfiguration. |
| TinySearch-Volume | Das vom Installer vorbereitete Modellvolume wurde von Compose gleichzeitig als Compose-eigen behandelt. | Das Volume besitzt einen festen Namen und ist in Compose ausdrücklich als extern vorbereitet markiert. |
| Reasoning-Filter | Beide globalen Filter besaßen Priorität 0; bei gleicher Priorität entschied die ID-Sortierung statt der gewünschten Logik. | `Reasoning Default Off` läuft mit Priorität 10 sicher vor dem optionalen `Thinking`-Override mit Priorität 20. Filter und sicherer Installer liegen versioniert im Repository. |
| Folgefragen | OpenWebUI erzeugte nach Antworten zusätzliche Vorschläge und verbrauchte dafür einen weiteren Modellaufruf. | Folgefragengenerierung ist in der persistenten OpenWebUI-Konfiguration und im Compose-Standard deaktiviert. |
| Werkzeug-/Kontextschutz | Große MCP-Antworten und wiederholte identische Aufrufe konnten Kontextfenster sprengen beziehungsweise Tool-Schleifen erzeugen. | Globaler Stability Guard begrenzt Resultate, verdichtet alte Inhalte profilabhängig und stoppt Wiederholungen; JSON-Schemas und Bilder werden nicht beschädigt. |
| Werkzeugauswahl | Überlappende oder zu allgemeine MCP-Beschreibungen führten zu falschen Werkzeugen, unnötigen Wiederholungen und paralleler Nutzung von MUA und Unraid-Diagnose. | Klare USE-/DO-NOT-USE-Texte auf Server- und Werkzeugebene; Web-Unterwerkzeuge sind nach Lookup, Verifikation, Shopping und Tiefenrecherche getrennt. Bestehende OpenWebUI-Verbindungen werden ohne Änderung von URL, Schlüssel oder Berechtigungen aktualisiert. |
| Leistungsdaten | Benchmarkdaten sollten sichtbar sein, ohne private Chat-Inhalte zu protokollieren. | Ein globaler Abschlussfilter schreibt ausschließlich technische Zahlen in eine lokal rotierende JSONL-Datei und zeigt eine knappe Statuszeile. |
| Antwortaktionen | Wiederkehrende Nachbearbeitungen sollten bewusst per Klick statt als permanenter Zusatzprompt laufen. | Eine versionierte globale Action bietet lokale Kurzfassung, Checkliste, Diagnose, Unsicherheits-/Quellenprüfung, Thinking-Verbesserung und Markdown-Kopie; keine Schreib- oder Profilwechselaktion. |
| Sprachausgabe | Beim ersten Leerhostaufbau war kein TTS-Dienst Bestandteil des Compose-Stacks. | Piper `piper-tts` 1.6.0 läuft als eigener interner CPU-Container mit persistenter deutscher Stimme; Open WebUI nutzt ihn ausschließlich über den authentifizierten Router. |
| Persistente Audioeinstellungen | Die restaurierte OpenWebUI-Datenbank überstimmte Compose mit dem alten Modell `tts-1` und der Stimme `coral`; der Router antwortete deshalb mit HTTP 400. | Der OpenWebUI-Konfigurator setzt bei Installation und Restore gezielt Engine `openai`, Modell `piper`, Stimme `alloy` und die interne Router-URL. Andere Audio- oder Nutzereinstellungen bleiben unangetastet. |
## Abnahmezustand am 21. August 2026
- Basisinstallation einschließlich Treiber, Docker, llama.cpp, Router und
Fast-Profil erfolgreich.
- Fast-Profil mit 76.800 Token Kontext gestartet und durch Readiness bestätigt.
- HA-, ARR-, Unraid- und Web-MCP als getrennte Container gestartet.
- OpenWebUI-Daten und freigegebene MCP-Konfiguration aus dem Referenzbackup
übernommen.
- Exakter OpenWebUI-Build anhand des gesicherten Registry-Digests und Commits
rekonstruiert.
- Vollständiger Restore ein zweites Mal erfolgreich und ohne Datenbankmigration
ausgeführt.
- OpenWebUI, Router und Fast-Inferenz sind gesund; HTTP-Zugriffe liefern Status
200 und der Router meldet `qwen-fast`, `qwen-medium` und `qwen-long`.
- Alle vier MCP-Endpunkte sind aus dem OpenWebUI-Netz per TCP erreichbar.
## Noch abzunehmen
1. Anmeldung und Profilwechsel über die Oberfläche ohne Lesen alter
Chat-Inhalte.
2. MCP-Protokolltest jedes Werkzeugs und Prüfung seiner Sicherheitsgrenze.
3. Neustarttest des gesamten Hosts.
4. WireGuard- und Fail-closed-Test am späteren Universitätsstandort.
5. Standardbenchmark mit RTX 5080 und anschließend mit der RTX 3060.
6. Push der lokalen Commits nach unabhängiger Prüfung des Git-Server-
Hostschlüssels.
Erst nach diesen Punkten gilt Athena als vollständig reproduzierbare
Referenzinstallation.
docs/BARE_METAL_RECOVERY.md
-186
View File
@@ -1,186 +0,0 @@
# Vollständige Bare-Metal-Wiederherstellung
Dieses Dokument ist die verbindliche Anleitung für den Verlust der Athena-
System-SSD. Wissen aus früheren Chats ist weder Voraussetzung noch gültige
Dokumentation.
## Was woher wiederkommt
| Bestandteil | Quelle beim Recovery |
|---|---|
| Plattform, Router, Profile, MCP-Builds und Patches | dieses Git-Repository, exakter Commit |
| Qwen-, Projektor- und Bildmodelle | dokumentierte URLs und SHA256 in `config/install.env.example` beziehungsweise der gesicherten Installationskonfiguration |
| Navidrome-MCP 2.2.0 samt llama.cpp-Schemafix | `platform/mcp/Dockerfile.navidrome` |
| OpenWebUI-Benutzer, Chats, Arbeitsbereichsmodelle, Filter und Verbindungen | verschlüsseltes Recovery-Bundle |
| Hermes-Sitzungen, Skills, Konfiguration und Arbeitsfläche | `/data/hermes` im verschlüsselten Recovery-Bundle |
| Router-, WireGuard-, HA-, ARR-, Unraid- und Navidrome-Zugangsdaten | verschlüsseltes Recovery-Bundle |
| Last.fm API-Key | `/etc/mike-ai/navidrome-mcp.env` im verschlüsselten Bundle |
| Navidrome-Bibliothek und Benutzer | bleiben auf dem separaten Unraid-Server |
Das Last.fm Shared Secret wird nicht verwendet und daher nicht gesichert.
Modelldateien müssen nicht im Bundle liegen: Der Installer lädt sie erneut und
verifiziert jede Datei kryptografisch. Ein vorhandenes intaktes `/data` kann
den Download lediglich beschleunigen.
## Einmalige Vorbereitung
Die geheime age-Identität muss **außerhalb Athenas** liegen, beispielsweise
auf dem Mac und zusätzlich in einem Passwortmanager oder Offline-Datenträger:
```bash
age-keygen -o athena-recovery.agekey
age-keygen -y athena-recovery.agekey > athena-recovery.recipient
```
Nur die öffentliche Zeile aus `athena-recovery.recipient` wird auf Athena als
`/etc/mike-ai/recovery.age-recipient` mit Modus `0600` abgelegt. Die Datei
`athena-recovery.agekey` darf niemals auf Athena oder im Git liegen.
## Sicherung erzeugen
Das Ziel muss nach einem SSD-Verlust noch existieren. Bevorzugt wird ein
gemountetes, ausschließlich für Backups beschreibbares Verzeichnis auf Unraid;
`/data` allein schützt nur vor dem Verlust der System-SSD, nicht vor Verlust
des gesamten Rechners.
```bash
sudo /opt/mike-ai/stack/platform/recovery/create-recovery-bundle.sh \
/PFAD/AUF/UNRAID/athena-recovery-$(date +%F).tar.age
```
Das Skript nimmt ausschließlich auf:
- `/etc/mike-ai` einschließlich aller Fach-MCP-Secrets,
- `/root/mike-ai-install.env`,
- das produktive Dokumentations-Overlay unter `/opt/mike-ai/stack/docs`,
- Vorschläge, Sicherungen und Auditstatus des Platform Context MCP unter
`/data/mike-ai-platform-context`,
- Hermes-Sitzungen, Skills, Konfiguration und Arbeitsfläche unter
`/data/hermes`,
- den kleinen eigenen Zustand der optionalen Hermes Community-WebUI unter
`/data/hermes-webui/state` (Agent-Code und Image werden reproduzierbar neu
erzeugt),
- das vollständige OpenWebUI-Datenvolume,
- Prüfsummen und den eingesetzten Git-Commit.
Der Klartext liegt nur in einem kurzlebigen root-only Verzeichnis unter
`/tmp` und wird beim Ende entfernt. Das Ergebnis ist vollständig mit age
verschlüsselt. Ohne erfolgreiche Ausgabe `RECOVERY_BUNDLE_OK` gilt die
Sicherung als fehlgeschlagen. Für ein konsistentes SQLite-Abbild verwendet das
Skript die Online-Backup-Schnittstelle der Datenbank. OpenWebUI, laufende
LLM-Profile und MCP-Dienste bleiben während der Sicherung verfügbar.
## Wiederherstellung nach SSD-Verlust
1. Debian 12 oder 13 installieren, Netzwerk herstellen und den administrativen
Benutzer aus der Installationskonfiguration anlegen.
2. Root-SSH-Zugriff mit dem vorhandenen Schlüssel herstellen.
3. Dieses Repository klonen und exakt den in `METADATA` des Bundles genannten
Commit auschecken. Normalerweise ist das der Commit, mit dem die Sicherung
erzeugt wurde.
4. Recovery-Bundle und `athena-recovery.agekey` temporär auf den Host kopieren.
5. Einen Befehl ausführen:
```bash
sudo ./platform/recovery/restore-recovery-bundle.sh \
/root/athena-recovery-YYYY-MM-DD.tar.age \
/root/athena-recovery.agekey
```
Der Wiederhersteller:
1. installiert nur die zum Entschlüsseln benötigten Basispakete,
2. prüft Verschlüsselung, Archivstruktur, SHA256 und Git-Commit,
3. stellt Installationskonfiguration und Secrets ohne Ausgabe ihrer Werte her,
4. führt den idempotenten Hostinstaller aus,
5. signalisiert einen notwendigen NVIDIA-/Netzwerk-Reboot mit Status 20/21;
danach wird derselbe Befehl erneut ausgeführt,
6. sichert den vorhandenen OpenWebUI-Stand als Rückfallarchiv und stellt dann
das geprüfte OpenWebUI-Datenvolume wieder her,
7. installiert die versionierten Modelleinstellungen, Filter und MCP-
Verbindungen erneut,
8. startet alle durch vorhandene Secret-Dateien freigegebenen Toolprofile,
9. prüft Navidrome, sämtliche Werkzeug-Schemas, Last.fm und den OpenWebUI-
Verbindungseintrag ohne Musik- oder Zugangsdaten auszugeben.
Erst die Ausgabe `BARE_METAL_RECOVERY_OK` bedeutet Erfolg.
## Navidrome-Abnahmekriterium
Bei vorhandenem `LASTFM_API_KEY` müssen 45 Werkzeuge erscheinen, andernfalls
38. Playback-Werkzeuge dürfen auf Athena nicht auftauchen. Sämtliche Regex-
Patterns müssen für llama.cpp vollständig mit `^…$` verankert sein. Eine
öffentliche Last.fm-Trendabfrage muss funktionieren; Bibliothek, Playlists und
Hörverlauf werden während der Abnahme nicht gelesen.
Die Prüfung kann jederzeit wiederholt werden:
```bash
sudo /opt/mike-ai/stack/platform/mcp/verify-navidrome.sh
```
## Regelmäßige Kontrolle
Mindestens nach jeder Änderung an OpenWebUI, WireGuard oder einem MCP-Secret
wird ein neues Bundle erzeugt und **außerhalb Athenas** aufbewahrt. Quartalsweise
wird ein Restore in einer isolierten Testinstallation durchgeführt. Eine
Sicherung ohne getestete Entschlüsselung und Abnahmemarker ist nur eine
Hoffnung, kein Backup.
## Maßgeblicher Recovery-Punkt
Der aktuell verwendete Commit steht im verschlüsselten `METADATA` des Bundles,
in `/opt/mike-ai/stack/.mike-ai-source-commit` und im begrenzten
Platform-Context-Snapshot. Eine hier hart eingetragene Commit-ID würde nach der
nächsten Plattformänderung sofort veralten und ist daher kein
Abnahmekriterium.
- Athena: neuestes geprüftes Bundle unter `/data/recovery/`
- zweite verschlüsselte Kopie auf dem Mac unter
`~/.config/mike-ai-recovery/bundles/`
- private age-Identität ausschließlich auf dem Mac:
`~/.config/mike-ai-recovery/athena-recovery.agekey`
- öffentliche Empfängerdatei auf Athena:
`/etc/mike-ai/recovery.age-recipient`
Für jeden neuen Recovery-Punkt muss die Mac-Kopie erfolgreich entschlüsselt
werden. Sämtliche inneren SHA256-Prüfsummen, der aufgezeichnete Git-Commit und
der konsistente `openwebui-data.tar.gz`-Datenbankeintrag müssen geprüft sein.
Der produktive OpenWebUI-Datenträger wird dabei nicht verändert. Dateien mit
dem Namensbestandteil `pre-online-backup` sind keine freigegebenen
Recovery-Punkte.
Noch organisatorisch zwingend: Die private age-Identität muss eine zweite,
vom Mac unabhängige Kopie in einem Passwortmanager oder auf einem Offline-
Datenträger erhalten. Ohne diese Identität ist das verschlüsselte Bundle nicht
wiederherstellbar.
## Selbsttragender Recovery-Koffer auf der Data-SSD
Für den speziellen Ausfall **nur der System-SSD** kann zusätzlich ein
vollständiger Recovery-Koffer unter `/data/mike-ai-recovery-kit` liegen. Er
enthält das verschlüsselte Bundle, den dafür benötigten Schlüssel, die gesamte
Git-Historie und ein eigenständiges Startskript. Auf einem frischen Debian:
```bash
mount <DATA-PARTITION> /data
sudo /data/mike-ai-recovery-kit/reinstall-athena.sh
```
Nach dem einmaligen Start läuft der Wiederaufbau selbständig. Falls NVIDIA-
Treiber oder der stabile Interface-Name einen Neustart erfordern, hinterlegt
das Skript einen systemd-Fortsetzer, bindet `/data` über die vorhandene UUID
dauerhaft ein und setzt den Ablauf nach dem Reboot fort. Nach drei erfolglosen
Versuchen bricht es gegen eine Bootschleife ab.
Diese Bequemlichkeit besitzt bewusst eine andere Sicherheitsgrenze: Weil der
Entschlüsselungsschlüssel auf derselben Data-SSD liegt, kann eine Person mit
Lesezugriff auf diese SSD auch die enthaltenen Secrets entschlüsseln. Das
separate Off-Host-Bundle mit getrennt verwahrtem Schlüssel bleibt daher die
maßgebliche Sicherung gegen Diebstahl oder Verlust des gesamten Hosts.
Der stabile Einstieg `/data/mike-ai-recovery-kit` zeigt immer auf das neueste
geprüfte, unveränderlich benannte Release. Sämtliche Kit-Dateien müssen per
SHA256 geprüft sein, das Git-Bundle muss den in `kit.env` geforderten Commit
enthalten und das Reinstall-Skript muss die Syntaxprüfung bestehen. Der
Abnahmemarker lautet `DATA_KIT_ACCEPTANCE_OK`.
docs/CLIENT_TOOL_STANDARD.md
-79
View File
@@ -1,79 +0,0 @@
# Client-unabhängiger Werkzeugstandard
## Ziel
Eine Aufgabe darf nicht nur deshalb scheitern, weil sie in Hermes oder Pi statt
in OpenWebUI gestellt wurde. OpenWebUI-Filter sind eine Komfort- und
Kontextoptimierung, aber niemals die eigentliche Berechtigungs- oder
Fähigkeitsschicht.
## Kernfähigkeiten für jeden vertrauenswürdigen VPN-Client
| Fähigkeit | MCP-Endpunkt | Zweck |
|---|---|---|
| Breiter Operator | `http://192.168.1.212:8202/mcp` | Terminal, Dateien, Docker, Git, Downloads, Konvertierung, APIs und SSH zu konfigurierten Systemen |
| Allgemeines Web | `http://192.168.1.212:8203/mcp` | Site-unabhängige Suche und Seitenabruf |
| Plattformwissen | `http://192.168.1.212:8201/mcp` | Aufbau, Ist-Zustand, Quellen und Änderungsablauf von Athena |
Diese drei Server bilden das tragfähige Minimum. Fach-MCPs wie Home Assistant,
MUA, ARR, Navidrome und GitHub ergänzen kurze strukturierte Operationen. Sie
sind der bevorzugte Weg, aber keine Voraussetzung: Fehlt eine Spezialfunktion,
bleiben allgemeines Web und Operator verfügbar.
## Client-Verhalten
- **OpenWebUI:** Native Websuche bleibt grundsätzlich verfügbar. Der Auto Tool
Selector hängt Fach-MCPs und den Operator anhand allgemeiner
Fähigkeitsklassen an. Allgemeine Hostarbeit wird anhand von Ausführungs- oder
Änderungsabsicht plus Host-, Datei-, Kommando- oder Dienstkontext erkannt;
nicht anhand einzelner Programme oder Websites.
- **Hermes:** Die drei Kernendpunkte werden in `~/.hermes/config.yaml`
eingetragen. Hermes verbindet sie beim Start, ruft MCP `tools/list` auf und
stellt die entdeckten Werkzeuge in jedem Gespräch bereit. Vorlage:
`config/hermes-mcp-core.yaml.example`.
- **Pi und weitere MCP-Clients:** Dieselben Streamable-HTTP-Endpunkte direkt
konfigurieren. Es ist kein OpenWebUI-Filter und kein zusätzlicher Proxy
erforderlich.
## Verbindliche Sicherheitsgrenze
Toolbeschreibungen und Systemprompts helfen dem Modell bei der Wahl, sind aber
keine Sicherheitsgrenze. Unverzichtbare Verbote, Ausgabelimits,
Schreibabläufe und Schutz vor dem Verlust der Remote-Erreichbarkeit werden im
MCP beziehungsweise im Athena-Operator-Dienst erzwungen. Dadurch gelten sie
identisch für OpenWebUI, Hermes, Pi und zukünftige Clients.
## Lange operative Aufgaben
Lange Arbeiten verwenden clientunabhängig das Muster
`Start -> kompakter Status -> Ergebnis/Verifikation`. Recherche wird vor der
Mutation abgeschlossen; Hilfsmittel werden gebündelt vorbereitet und lange
Kommandos asynchron gestartet, wenn ein synchroner Werkzeugaufruf in ein
Zeitlimit laufen könnte. OpenWebUI gewährt dieser allgemeinen Aufgabenklasse
ein höheres, aber weiterhin endliches Ausführungsbudget: 64 Aufrufe insgesamt
und 24 je Werkzeug. Normale Recherche bleibt bei 40 beziehungsweise 12. Das
ist keine Sonderregel für YouTube, ffmpeg, MUA oder einen bestimmten Server.
## Lebensdauer von Hilfsprogrammen
Die Absicht des Benutzers bestimmt die Lebensdauer einer Abhängigkeit:
- **nutzen, ausführen, testen, ausprobieren:** zuerst ein vorhandenes Programm
verwenden; fehlt es, nur eine auftragsbezogene Kopie unter `/tmp` oder im
temporären Arbeitsbereich ablegen und nach der Verifikation entfernen;
- **installieren, einrichten, dauerhaft bereitstellen:** reproduzierbar und
persistent über die versionierte Plattformkonfiguration installieren;
- **unklare Formulierung:** flüchtig bleiben und im Ergebnis offen angeben,
was temporär verwendet wurde.
Diese Regel gilt für alle Clients und Zielsysteme. Sie ist nicht auf FFmpeg,
Downloads oder Unraid beschränkt.
## Community-Bezug
Das folgt dem MCP-Modell: Ein Client verbindet einen vertrauenswürdigen
Streamable-HTTP-Server und entdeckt dessen Werkzeuge über `tools/list`.
Hermes registriert konfigurierte HTTP-MCPs beim Start als normale Werkzeuge;
OpenWebUI registriert Remote-MCPs global und kann sie pro Anfrage über
`tool_ids` aktivieren. Clientseitige Auswahl optimiert Kontext und Bedienung,
serverseitige Regeln bleiben maßgeblich.
docs/COMPONENTS.md
-34
View File
@@ -1,34 +0,0 @@
# Komponentenverzeichnis
| Bestandteil | Quelle | Bestandteil dieses Repositories | Status |
|---|---|---|---|
| AI Profile Router | `router/` | vollständig | Kern |
| llama.cpp | ggml-org/llama.cpp, festgeschriebener Commit | Buildskript und Commit | Kern |
| Qwen-Profile | `platform/profiles/` | vollständig, Modelle ausgenommen | Kern |
| MCP-Tool-Stack | `platform/mcp/compose.yaml` | vollständig | Kern |
| Hermes Agent | NousResearch Hermes Agent 0.20.5, OCI-Digest gepinnt | eigener Clientcontainer, Dashboard/API, persistente Daten unter `/data/hermes` | Kern |
| Hermes Community-WebUI | nesquena/hermes-webui 0.52.113, OCI-Digest gepinnt, kleine lokale Kompatibilitätsschicht | optionale mobile Browseroberfläche über Hermes-Gateway; installiert Abhängigkeiten aus Hermes 0.20.5 ohne dessen absichtlich gesperrten Wheel-Build; eigener Zustand unter `/data/hermes-webui` | Optional |
| Hermes Athena-Operator-Skill | `platform/hermes/skills/athena-operator/SKILL.md` | knappe, versionierte Arbeitslogik für Plattformwissen, Operator, Rollback, Verifikation, Git und Recovery; wird in alle Hermes-Profile synchronisiert | Kern |
| Websuche | SearXNG + TinySearch/Crawl4AI | intern, ohne veröffentlichten Port | Kern |
| Allgemeines Web | OpenWebUI native Suche; TinySearch-Upstream-MCP auf VPN-Port 8203 für andere Clients | site-unabhängig; keine neue Implementierung pro Website | Kern |
| Frühere Web-MCP-Fassade | `platform/web-search/web_search_mcp.py` | nur Rollback-Profil `legacy-web` | Altbestand |
| Home-Assistant-MCP | HA-Endpunkt plus lokaler Relay | eigener optionaler Container | optional |
| ARR-MCP | `arr-mcp` 1.0.1 plus dokumentierter Sonarr-Patch | eigener optionaler Container | optional |
| Navidrome-MCP | Blakeem/Navidrome-MCP 2.2.0, Image per OCI-Digest | eigener optionaler Container ohne mpv | optional |
| GitHub-MCP | offizieller `github/github-mcp-server` 1.10.1, drei begrenzte read-only Werkzeuge | eigener optionaler Container hinter Streamable-HTTP-Brücke | optional |
| Platform Context MCP | kurze Athena-Auskunft und begrenzter Laufzeitsnapshot | read-only Container ohne Docker-Socket, Shell, Egress oder Secrets | Kern |
| Athena Operator MCP | Entwicklung und vollständiger Betrieb der KI-Plattform | sechs Werkzeuge: Inspect, Suche, Lesen, Terminal, Änderung, Job | Kern |
| Operator-Kontext | `ATHENA.md` plus Hermes-Skill `athena-operator` | kurze, versionierte Betriebslogik für Qwen | Kern |
| Unraid/MUA | MUA r023+ auf dem HomeServer, direkter MCP-Endpunkt | read-only Automatik; serverseitig begrenzte Diagnoseausgaben; begrenzte Datei-/Medieninventare; Verwaltung bei explizitem Änderungsauftrag; idempotente Batch-Updates; asynchrone Jobs mit Start/Status/Aufräumen für lange Arbeiten | Kern |
| Whisper | ggml-org/whisper.cpp | Service im Router-Deploy | optional |
| XTTS-v2 | Coqui, offizielles CUDA-12.1-Image per Digest | RTX-3060-Container, Stimme `Annmarie Nele`, CPML | Kern |
| TTS-Gateway | `platform/docker/tts-gateway/` | interne Queue, stabile deutsche Satzblöcke, automatische Erkennung rein englischer Texte und Piper-Fallback | Kern |
| Piper TTS | Open Home Foundation, `piper-tts` 1.6.0 | interner CPU-Fallback, Stimme `de_DE-thorsten-high` | Kern |
| FLUX.2 klein | Black Forest Labs | Worker und Modellmanifest | optional |
| LLama-GUI | separates Upstream-Projekt | nur Betriebsrolle dokumentiert | optional |
| Glances | Distribution | nur Betriebsrolle dokumentiert | optional |
Upstream-Komponenten werden nicht ungeprüft einkopiert. Images, Python-Pakete
und lokale Patches sind in Dockerfiles, Compose-Mounts und Dokumentation
explizit benannt. So bleiben Zuständigkeiten klar und Updates können
unabhängig getestet werden.
docs/CURRENT_REFERENCE.md
-456
View File
@@ -1,456 +0,0 @@
# Aktueller produktiver Referenzstand
Stand: 24. August 2026. Dieses Dokument beschreibt die auf Athena installierte
und geprüfte Docker-Referenz. Die verbindlichen Profilparameter stehen in
`STANDARD_PROFILE_MATRIX.md`.
## Hardware und Betriebssystem
| Bereich | Referenz |
|---|---|
| Betriebssystem | Debian 13 `trixie` |
| Kernel | 6.12.101+deb13-amd64 |
| CPU | AMD Ryzen 5 5600, 6 Kerne/12 Threads |
| RAM | 48 GiB DDR4-2666 |
| GPUs | NVIDIA GeForce RTX 5080, 16 GiB + RTX 3060, 12 GiB VRAM |
| NVIDIA-Treiber | 610.57.04 |
| System-SSD | Samsung 980 PRO 1 TB |
| Daten-SSD | WD Blue SN580 1 TB, unter `/data` |
Die früher verwendete Radeon RX 470 ist ausgebaut und gehört nicht zur
Zielplattform.
## Produktiver Text-Stack
| Eigenschaft | Aktueller Wert |
|---|---|
| Runtime | llama.cpp |
| Repository | `https://github.com/ggml-org/llama.cpp.git` |
| Commit | `3f545beccee69d9975f466ec7e45fd9aacd8ba90` |
| Compiler | GCC 14.2 |
| Hauptdienst | jeweils ein Container `mike-ai-llama-<profil>` |
| llama.cpp-Port | 8080, ausschließlich im internen Docker-Netz |
| Client-Port | 8081 über den Router |
| MCP-Konfiguration | getrennte Container unter `/opt/mike-ai/stack/platform/mcp` |
### Aktives Standardprofil
- Qwen3.8-27B IQ4_XS Pure
- Dateigröße: 14.534.384.640 Bytes
- SHA256: `ea5a3c45d407f9b9e5d2c0d647f0ea600f486f6b86b92b56d0823ba073dae675`
- Quelle: `jpetrina/Qwen3.8-27B-IQ4_XS-pure-GGUF`
- Kontext 160.000
- RTX 5080 + RTX 3060 im Verhältnis 90:10
- Flash Attention
- KV-Cache Q4_0 für K und V
- explizites Prompt-Caching mit 8.192 MiB profilinternem RAM-Cache
- exakte Wiederverwendung bereits verarbeiteter Prompt-Präfixe über
`--cache-prompt`; Hermes trennt seinen System-Prompt zusätzlich in einen
stabilen, einen kontextabhängigen und einen flüchtigen Teil
- `--cache-reuse 256` nur in den text-only-Profilen Ultra und Experimental;
llama.cpp deaktiviert diese unscharfe Wiederverwendung ausdrücklich, sobald
ein Vision-Projektor geladen ist
- kein persistenter Slot-Cache auf Datenträger, bis die bekannten
llama.cpp-Restore-Regressions behoben sind
- MTP Draft, maximal drei Tokens
- MTP-Akzeptanzschwelle 0,05; im Referenzlauf 77,26 statt 73,88 Tok/s
- sechs Threads und sechs Batch-Threads
- Batch 64, Micro-Batch 32
- ein paralleler Slot
- Jinja und automatisches Reasoning
- erhaltener Reasoning-Zustand über Werkzeugrunden (`--reasoning-preserve`)
- Medium/Hermes: Thinking-Sampler gemäß Qwen-Empfehlung mit Temperatur 1,0,
Top-p 0,95 und Top-k 20
- Medium/Hermes: maximal 8.192 Reasoning-Token pro einzelner Denkphase;
Werkzeugrunden erhalten jeweils eine neue Denkphase
- andere Profile: Temperatur 0,2, Top-p 0,8, Top-k 20
### Profile
| Profil | Virtuelles Modell | Kontext | Besonderheit |
|---|---|---:|---|
| Fast | `qwen-fast` | 76.800 | IQ4-MIX, MTP2, Text auf RTX 5080, mmproj auf RTX 3060 |
| Medium **(Standard)** | `qwen-medium` | 160.000 | IQ4_XS Pure, MTP3, beide GPUs 90:10, mmproj auf RTX 3060 |
| Large | `qwen-large` | 192.000 | IQ4_XS Pure, MTP3, beide GPUs 86:14, mmproj auf RTX 3060 |
| Ultra | `qwen-ultra` | 262.144 | IQ4_XS Pure, MTP2, beide GPUs 80:20, text-only; 68,2 Tok/s und 220K-Fülltest bestanden |
| Uncensored | `qwen-uncensored` | 80.000 | Abliterated Q4_K_M, MTP2, beide GPUs 90:10, eigener mmproj auf RTX 3060; etwa 52,2 Tok/s |
## Router
- Container: `mike-ai-router`
- Port: 8081
- Upstream: `llama-upstream:8080` im internen Inferenznetz
- Commit des Plattform-Repositories: siehe jeweils aktuelles `main`
- Umschaltung: `mike-ai-profile-controller` mit fester Container-Allowlist
- Timeout für Profilwechsel und Requests: 600 Sekunden
Der Router übernimmt:
- OpenAI-kompatibles Chat-Proxying und Streaming
- Übersetzung von OpenAI-/Hermes-`reasoning_effort` in die vom
Qwen3.8-Jinja-Template tatsächlich ausgewerteten
`chat_template_kwargs`: `none` deaktiviert Thinking mit
`enable_thinking: false`; `low` und `medium` bleiben erhalten; höhere
Client-Stufen werden auf das vom Modell unterstützte `xhigh` begrenzt.
Das ist absichtlich zentral im Router implementiert, damit Hermes,
OpenWebUI und weitere OpenAI-kompatible Clients identisches Verhalten haben.
- virtuelle Modelle und automatische Profilumschaltung
- Tool Calls
- direkte integrierte Vision in Fast, Medium, Large und Uncensored
- FLUX-Hotswap zur Bildgenerierung
- Whisper Speech-to-Text
- XTTS-v2 über das TTS-Gateway als primäre Text-to-Speech-Ausgabe
- Piper als automatischer CPU-Fallback
- Zustands- und Modellendpunkte
## Hermes Agent
- Hermes 0.20.5 baut den Systemprompt bereits in drei geordneten Bereichen:
einen chatübergreifend stabilen Präfix, sitzungsstabilen Kontext und einen
variablen Nachlauf. Der stabile Präfix bleibt bei gleicher Profil- und
Werkzeugkonfiguration wortgleich und kann dadurch vom llama.cpp-RAM-Cache
wiederverwendet werden.
- Der RAM-Promptcache lebt nur so lange wie der jeweilige llama.cpp-Prozess.
Ein Profilwechsel entlädt das bisherige Modell und damit dessen Cache.
- Persistente Slot-Dateien (`--slot-save-path`) sind vorerst bewusst nicht
aktiviert. Die aktuelle llama.cpp-Linie hat offene Restore-Fehler; ein
gemeldetes erfolgreiches Restore kann trotzdem einen vollständigen Prefill
auslösen. Erst nach einem isolierten Regressionstest aktivieren.
- Kontextkompression läuft spätestens bei 60.000 Token; die relative
65-Prozent-Grenze greift nur, wenn sie noch früher erreicht wird. Damit gilt
dieselbe Obergrenze auch für Medium, Large und Ultra und ein Profilwechsel
zurück zu Fast bleibt möglich. Alte große Werkzeugausgaben werden ab 50.000 Token zunächst
ohne Modellaufruf bereinigt; `tail_mode: lean` hält nach der Kompression einen
kleinen, zusammenhängenden jüngsten Abschnitt. Dadurch sollen keine
mehrfachen minutenlangen Zusammenfassungen eines bereits weit überfüllten
Threads mehr nötig werden.
- Die Kompressionszusammenfassung nutzt weiterhin dasselbe aktive Modell. Ein
kleineres Fast-Modell wäre zwar schneller, besitzt aber nicht genug Kontext,
um die vollständige Mitte einer Medium-, Large- oder Ultra-Sitzung sicher zu
verarbeiten. `reasoning_effort: none` wird vom Router in
`enable_thinking: false` übersetzt und vermeidet damit nachweislich
unnötiges Nachdenken beim reinen Zusammenfassen. Ein unverändert an
llama.cpp gesendetes Top-Level-`reasoning_effort` wäre wirkungslos.
- `Summarizing thread` ist eine echte zusätzliche Modellanfrage. Bei sehr alten
Sitzungen kann die Desktop-Anzeige nach abgeschlossener Kompression außerdem
veraltet stehen bleiben. Maßgeblich sind dann Sitzungsfortschritt und
Backend-Log, nicht das Label allein.
- Container: `mike-ai-hermes`
- Standardsprache: Deutsch (`display.language`, deutsches `SOUL.md`)
- Spracheingabe: lokales Faster-Whisper, Modell `base`, Sprachhinweis `de`
- Sprachausgabe: Athena-TTS über die OpenAI-kompatible Router-API; XTTS v2
mit **Annmarie Nele**, Piper als automatischer Fallback
- Bei einer entfernten Hermes-Desktop-App läuft Audio bewusst über das
Hermes-Backend (`voice.client_direct: false`), weil Router und TTS nur im
internen Docker-Netz erreichbar sind.
- Version: 0.20.5, lokales abgeleitetes Image
`mike-ai/hermes-agent:0.20.5-mcpfix1`; dessen Basis ist das offizielle
Hermes-Image per OCI-Digest gepinnt.
- Die gepinnte Version trägt beim Containerstart zwei eng geprüfte lokale
Upstream-Workarounds: API-Agenten übernehmen den live registrierten
MCP-Katalog (Hermes-Issue 69746), und `tool_search` veröffentlicht auch
geänderte Katalogbeschreibungen bei gleichbleibenden Brückennamen
(Hermes-Issue 72560). Der Start bricht bei unbekannt verändertem
Upstream-Code ab, statt blind zu patchen.
- Standardmodell: `qwen-medium`, 160.000 Kontext, über den Profile Router
- Dashboard: WireGuard-Port 9119 mit Basic-Auth
- Agent-API: WireGuard-Port 8642 mit eigenem Bearer-Key
- Profile: Fast 76,8K, Medium 160K, Large 192K, Ultra 262K und Uncensored
80K; alle verwenden dieselben MCPs, Skills, Sprach- und Sicherheitsvorgaben
- Profilübergreifende Latenzgrenzen: höchstens 8.192 Ausgabetoken je
Modellaufruf (sichtbare Antwort, Tool-Aufruf und verborgenes Denken
zusammen), Standard-Reasoning `minimal`; höhere Denkstufen bleiben pro Sitzung
über `/reasoning` wählbar.
- Automatische Sitzungstitel sind deaktiviert. Sie sind kosmetisch, erzeugten
aber auf dem einzelnen llama.cpp-Slot nach dem ersten Turn konkurrierende
Modellaufrufe und wiederholte 30-Sekunden-Timeouts.
- Hermes lädt als feste lokale Werkzeuge nur Web, Terminal, Dateien, Skills,
Aufgaben, Memory, Vision und TTS. Überschneidende große Built-ins wie
Browser-Automation, Session-Suche, Delegation und Clarify werden nicht in
jeden Prompt injiziert. Alle externen Athena-MCPs bleiben vollständig über
die verzögerte Werkzeugsuche verfügbar. Dadurch sank der feste Schema-Block
im Referenztest von 50.670 auf 27.556 Byte.
- Der verwaltete Skill `athena-operator` wird aus dem Repository in das
Standardprofil und alle fünf benannten Profile synchronisiert. Er enthält
nur die verbindliche Arbeitslogik; Architektur und Ist-Zustand werden
bedarfsgerecht aus Platform-Context- und Operator-MCP gelesen.
- persistenter Zustand: `/data/hermes`
- lokales Terminal: ausschließlich `/data/hermes/workspace` im Container
- MCPs: Athena-Plattform, Athena-Operator, allgemeines Web, GitHub, Home
Assistant, ARR, Navidrome und ein gemeinsamer MUA-Unraid-Zugang
- Der Home-Assistant-Eintrag heißt in Hermes intern `homeassistant-admin`.
`homeassistant` kollidiert mit Hermes' deaktiviertem eingebautem Toolset und
würde den gesunden externen MCP aus dem Agentenkatalog filtern.
- Ein Agententurn ist standardmäßig auf 64 Schritte und acht Websuchen
begrenzt. Lange Implementierungen setzen nach einem belegten Zwischenstand
in einem frischen Turn fort; bekannte Container werden direkt inspiziert,
statt ungezielt vollständige Hostinventare in den Kontext zu laden.
- kein Docker-Socket, kein Host-Root-Mount und keine Veröffentlichung auf der
Universitätsadresse
- Start verweigert, wenn die verwaltete Konfiguration nicht lesbar ist oder
nicht ausdrücklich `custom` und den lokalen Router als Provider nennt
- Optionale Community-WebUI 0.52.113 auf WireGuard-Port 8787: eigener
Container und eigener Zustand unter `/data/hermes-webui`; Chats laufen über
die vorhandene Hermes-Gateway-API. Der vom Upstream-Entrypoint benötigte
gemeinsame Hermes-Home-Mount ist beschreibbar; UI-eigener Zustand bleibt
davon getrennt. Änderungen in WebUI-Einstellungen wirken daher bewusst auf
die zentrale Hermes-Konfiguration. Eine schreibgeschützte Kopie des exakt
gepinnten Hermes-Agent-Codes liegt unter `/data/hermes-webui/hermes-agent`,
damit Modell-, Skill- und Sitzungsfunktionen nicht im reduzierten Modus
laufen; der Installer erneuert sie nur bei geändertem Hermes-Image. Der
kleine Container `mike-ai-hermes-webui-vpn-proxy` teilt ausschließlich den
Netzwerk-Namespace des WireGuard-Gateways und hält Port 8787 rebootfest,
ohne das Gateway für Installation oder Entfernung neu zu erstellen.
## Vision
| Bereich | Referenz |
|---|---|
| Text-/Visionmodell | jeweils aktives Qwen3.8-27B-Profil |
| Projektor | BF16-mmproj |
| Speicherort des Projektors | RTX 3060 (`MTMD_BACKEND_DEVICE=CUDA1`) |
| Kontext | entspricht Fast/Medium/Large; Ultra ist bewusst text-only |
Vision ist Bestandteil von Fast, Medium, Large und Uncensored. Der Router prüft Bildgröße und URL,
leitet das Bild dann direkt weiter und führt keinen Modellwechsel mehr aus.
## Bildgenerierung
- Modell: FLUX.2 Klein 4B Distilled, Apache-2.0
- Runtime: eigener PyTorch-2.11/CUDA-12.8-/Diffusers-0.40-Container
- fest auf vier Schritte und Guidance 1,0 destilliert
- Worker läuft ausschließlich auf der RTX 5080 und ist im Normalbetrieb gestoppt
- der Controller beendet Qwen vor dem Job; Bildprompts bleiben im internen Netz
- Worker wird nach jedem Job vollständig beendet
- Qwen wird anschließend mit exakt dem vorherigen Profil wiederhergestellt
- gemessene reine Bildgenerierung bei 1024 × 1024: 11,67 bis 14,59 Sekunden
- gemessener kompletter Hot-Swap einschließlich Qwen-Wiederherstellung: etwa 31 Sekunden
- OpenWebUI ist global auf den OpenAI-kompatiblen Router-Endpunkt, vier Schritte
und 1024 × 1024 Pixel vorkonfiguriert
- OpenWebUI zeigt aus Kompatibilitätsgründen den Alias `gpt-image-1`; tatsächlich
rechnet ausschließlich das lokale FLUX.2-Klein-Modell, es fließen keine Daten
an OpenAI
- Bilder werden zwischen Router und OpenWebUI als eingebettete Base64-Daten
übertragen. Dadurch bleibt OpenWebUIs SSRF-Schutz für private URLs aktiv,
ohne die lokale Bildrückgabe zu blockieren
## Sprache
### Whisper
- Modell: large-v3-turbo
- lokale Standardsprache: Deutsch
- CPU-Ausführung
- acht Threads im produktiven Worker
- Port 8084, nur localhost
- ffmpeg für Eingabeumwandlung
### XTTS
Der aktuelle Docker-Stack nutzt Coqui XTTS-v2 als primäre Sprachausgabe.
Der isolierte Eignungs- und Ausfalltest ist in
[`XTTS_EVALUATION_2026-08-23.md`](XTTS_EVALUATION_2026-08-23.md) dokumentiert.
- Modell: Coqui XTTS-v2, offizielles CUDA-12.1-Image per Digest gepinnt
- GPU: ausschließlich RTX 3060 über ihre stabile GPU-UUID
- Stimme: `Annmarie Nele`
- Deutsch und Englisch; bekannte englische IT-Begriffe werden segmentiert
- kein veröffentlichter Port, nur Docker-intern erreichbar
- serielles TTS-Gateway vor XTTS, weil der Server nur einen Auftrag zugleich
zuverlässig verarbeitet
- Piper mit `de_DE-thorsten-high` bleibt als automatischer CPU-Fallback aktiv
- OpenWebUI behält aus Kompatibilitätsgründen `model=piper` und `voice=alloy`;
der Router leitet diese Werte an das Gateway weiter
## Websuche
- Docker Compose
- SearXNG, per Digest gepinnt
- TinySearch 0.6.1, per Digest gepinnt
- TinySearch ausschließlich im internen Docker-Netz, ohne Host-Port
- lokale ONNX-Embeddings
- OpenWebUI-native allgemeine Suche und Seitenabruf in allen normalen Profilen
- portabler TinySearch-Upstream-MCP mit vier breiten Werkzeugen auf VPN-Port 8203
- die frühere sechsfach spezialisierte Web-Fassade ist nur noch Rollback-Profil
- aktuelle Suchen erhalten keinen pauschalen Wikipedia-Fallback
- strukturierter API-Pfad für Hugging Face; GitHub-Quellcode läuft über den
getrennten offiziellen GitHub-MCP
## MCP-Referenz
Aktuell existieren funktionale Adapter für:
- Athena-Plattformwissen und begrenzter read-only Laufzeitsnapshot
- Athena Operator: Entwicklung, Docker/MCP/Modelle, Tests, Git und Recovery
- Websuche
- Home Assistant
- Sonarr/Radarr
- GitHub Repository read-only (offizieller Server, drei begrenzte Werkzeuge)
- Navidrome-Bibliothek und Last.fm-Empfehlungen
- Unraid read-only
- eigener Unraid-Administrationsserver
OpenWebUI bindet nicht pauschal sämtliche großen Fachkataloge ein. Der lokale
`MikeAI Auto Tool Selector` hält das allgemeine Web immer verfügbar und ergänzt
anhand der jüngsten Nutzernachricht alle passenden Fach-MCP-Verbindungen. Eine echte
Mehrdomänen-Aufgabe erhält automatisch ein begrenztes mittleres Reasoning-
Budget; einfache Aufgaben bleiben schnell. Allgemeine
Webrecherche erfolgt über Open WebUIs native `search_web`/`fetch_url`-Werkzeuge;
für andere Clients liegt TinySearch direkt auf Port 8203. Dadurch bleiben
Fachkataloge klein und kurze Profile verlieren keinen unnötigen Kontext. Reine
Unraid-Abfragen erhalten nur MUA read-only. Verlangt die aktuelle Nachricht
ausdrücklich eine Unraid-Änderung, stellt die Automatik zusätzlich den
Verwaltungszugang für die feste Kette Prüfen → Ändern → Verifizieren bereit.
Die Bereitstellung ersetzt niemals die ausdrückliche Änderungsanweisung.
Unraid ist ausschließlich über das MUA-Plugin angebunden. Die Verbindungen
`mua-readonly-local` und `mua` nutzen denselben MUA-Endpunkt. Mehrere bestätigte
Docker-Updates laufen ab MUA r019 gebündelt und idempotent; echte Image-IDs
verhindern Neuerstellungen aufgrund eines veralteten Statuscaches.
Ab MUA r021 inventarisiert `unraid_files_inventory` Datei- und Ordnernamen
begrenzt, ohne Dateiinhalte zu lesen, und beendet eine gefilterte Erkennung an
einem passenden Sammlungsordner. Auto Tool Selector 3.5 hält ausdrücklich
lesende Bibliotheksprüfungen bei MUA read-only und verwechselt Hörspielfolgen
nicht mit Sonarr-Episoden. Verlangt derselbe Auftrag aktuelle Onlinebelege,
aktiviert er zusätzlich die native Websuche. Der Ablauf steht in
`docs/UNRAID_MEDIA_AUDIT_WORKFLOW.md`. Der frühere GraphQL-basierte Unraid-MCP wurde
entfernt und gehört weder zum Start noch zum Recovery.
Ab MUA r022 stehen für lange, explizit autorisierte Arbeiten zusätzlich
`unraid_system_job_start`, `unraid_system_job_status` und
`unraid_system_job_cleanup` bereit. Der Start kehrt sofort mit einer Job-ID
zurück; Statusabfragen liefern nur kompakte, redigierte Ausgaben. Damit blockiert
ein Download, Transcode oder vergleichbarer Auftrag weder Open WebUI noch Hermes
oder Pi bis zum Prozessende. Die drei Werkzeuge erben dieselbe ausdrücklich
erteilte Berechtigung wie die uneingeschränkte Shell.
Ab MUA r023 begrenzt `unraid_system_shell_readonly` seine Ausgabe bereits auf
dem Unraid-Server standardmäßig auf 12.000 Zeichen; pro Aufruf sind explizit
1.000 bis 30.000 Zeichen möglich. Auto Tool Selector 4.7 ergänzt für offene
Diagnosen eine allgemeine Beweiskette: kompakten Status oder Benachrichtigung
prüfen, das neueste exakte Artefakt lokalisieren, nur entscheidende Zeilen
lesen, die führende Ursache mit einem unabhängigen Fakt bestätigen und dann
antworten. Vollständige Konfigurationen, rekursive Verzeichnisbäume und breite
historische Logs sind kein zulässiger Standardweg.
Auto Tool Selector 4.7 kennzeichnet allgemeine lange Operator-Aufgaben
produktunabhängig. Der OpenWebUI-Agentenloop stellt dafür bis zu 64
Werkzeugausführungen insgesamt und 24 je Werkzeug bereit; normale Aufgaben
bleiben bei 40/12. Zusätzlich verlangt der Systemhinweis das generische
Start-Status-Ergebnis-Muster und reserviert den Abschluss für Verifikation,
Zielablage und Aufräumen.
Der GitHub-Container läuft produktiv. Token-Datei, interner
Streamable-HTTP-Handshake, fehlende Host-Portfreigabe und exakt drei
read-only Werkzeuge wurden am 24. August 2026 verifiziert.
Die Transportbrücke verwendet den OpenWebUI-kompatiblen `mcp-proxy` 0.12.0 im
stateless Betrieb. Supergateway wurde nach reproduzierbaren HTTP-400-Fehlern
bei `notifications/initialized` aus diesem Pfad entfernt.
Die agentische OpenWebUI-Schleife führt bei normalen Aufgaben höchstens 40
einzelne Werkzeuge und höchstens zwölf Aufrufe desselben Werkzeugnamens aus.
Allgemeine lange Operator-Aufgaben erhalten 64 beziehungsweise 24. Exakt
dieselbe Signatur bleibt stets auf zwei Wiederholungen begrenzt. Nach Ende des
Budgets stehen zusätzliche interne Runden ausschließlich für eine sichtbare
werkzeugfreie Schlussantwort bereit. Das produktive OpenWebUI-Derivat trägt
den Tag `mike-ai/openwebui:main-01f4282-agent-loop-v9`.
Das in V9 enthaltene Verhalten aus V8 begrenzt zusätzlich die
Werkzeugantworten in OpenWebUIs internen Fortsetzungsrunden auf 12.000 Zeichen
je Ergebnis und 64.000 Zeichen pro Antwortlauf. Damit greift die Begrenzung
auch bei Ergebnissen, die erst nach dem ersten Request entstehen.
Auto Tool Selector 4.3 hält native Websuche immer verfügbar, ergänzt bei
expliziter Webrecherche den TinySearch-Fallback und erkennt unter anderem
`Home Assistant`, `Home-Assistant` sowie direkte `ha_*`-Werkzeugbezüge. Für
Home Assistant verlangt er gezielte Zustandsabfragen und verbietet die
Ableitung einer `entity_id` aus einer YAML-`id`.
Auto Tool Selector 4.3 ergänzt ein site-unabhängiges Marketplace-Protokoll.
Es begrenzt normale Kaufsuchen auf wenige fokussierte Recherche- und
Verifikationsschritte, nutzt Ergebnis-/Kategorieseiten bei blockierten
Detailseiten und verlangt einen aktuellen Beleg, bevor ein Angebot als aktiv
bezeichnet wird. Dafür existiert kein eBay-, MakerWorld- oder Shop-spezifischer
MCP. OpenWebUI V8 setzt für erkannte Marketplace-Aufträge über beide breiten
Webengines zusammen höchstens drei Such- und fünf Abrufoperationen durch;
danach folgt die sichtbare Synthese aus den vorhandenen Belegen.
Der produktive eBay-Praxistest am 24. August 2026 endete nach exakt drei
TinySearch-Suchen und drei konkreten Seitenabrufen. Qwen lieferte danach eine
sichtbare Antwort, trennte verifizierte, plausible und nicht verifizierbare
Angebote und sortierte Notebook, Zubehör sowie ein Ersatzteilgerät aus. Das
belegt sowohl die technische Grenze als auch eine brauchbare Synthese; ein
eBay-spezifischer MCP war nicht erforderlich.
Auto Tool Selector 4.6 erkennt zusätzlich allgemeine operative Arbeit über
Fähigkeitsklassen: Eine ausdrückliche Ausführungs- oder Änderungsabsicht in
Verbindung mit Host, Dateisystem, Kommando, Dienst, Pfad oder typischen
Kommandozeilenwerkzeugen stellt den Athena Operator bereit. Dadurch benötigen
neue Programme wie Download- oder Medienwerkzeuge keine eigene Selector-Regel.
Bei Unraid-Arbeit werden MUA für kompakte Bestandsaufnahme und der Operator für
die ausdrücklich verlangte allgemeine Schreibarbeit gemeinsam angeboten.
Lange Operator-Aufgaben werden dabei produktunabhängig markiert und folgen dem
Start-Status-Ergebnis-Muster, damit Recherche und Vorbereitung nicht das
Budget für Ausführung, Verifikation und Aufräumen verbrauchen.
Für andere Clients gilt `docs/CLIENT_TOOL_STANDARD.md`. Hermes lädt die drei
Kern-MCPs Web, Operator und Plattformwissen direkt per Streamable HTTP; die
Vorlage liegt unter `config/hermes-mcp-core.yaml.example`. Damit hängt die
Fähigkeit nicht vom OpenWebUI-Filter ab.
Der Platform Context MCP läuft ohne Docker-Socket, Shell, Egress oder Secrets.
Ein root-eigener Minutentimer erzeugt nur einen begrenzten Laufzeitsnapshot.
Der Schreibpfad ist auf `docs/*.md`, Vorschau, ausdrückliche Freigabe, atomare
Sicherung und sichtbare Git-/Recovery-Nacharbeit begrenzt.
Der Athena Operator MCP ersetzt die frühere begrenzte Terminal-Fassade. Er ist
die zusammenhängende Bedienebene, mit der Qwen die KI-Plattform selbst
weiterentwickeln und betreiben kann. Quellenlesen, Dateiänderungen, Tests,
Compose-Deployments, Containeraktionen, Modell-Downloads, Benchmarks,
Git-Publishing und Recovery sind strukturiert verfügbar. Zusätzlich bietet er
ein breites, ausgabebegrenztes Root-Terminal für Docker, Dateien, Git, HTTP,
Modelle und SSH zu konfigurierten Zielsystemen. Strombefehle und Änderungen an
Athenas SSH, Netzwerk, WireGuard, Firewall, Boot, Kernel, Mounts und Partitionen
sind serverseitig blockiert.
Ein separater allgemeiner Shell-MCP wird nicht benötigt; die breite Fähigkeit
ist portabel im Athena Operator auf VPN-Port 8202 enthalten.
Seit Operator 2.3 werden kleine Änderungen als SHA-geschützte Unified Diffs
über `patch_update` übertragen. `mcp_release` fasst den üblichen vollständigen
MCP-Ablauf in einem bestätigten Auftrag zusammen: Patch, Tests, benannter
Deploy, OpenWebUI-/Hermes-Sync, selektiver Git-Publish und Recovery. Geprüfte
Staging-Dateien werden per Pfad und SHA importiert. Damit muss das Modell weder
lange MCP-Quellen noch komplette Compose- oder Installationsdateien
rekonstruieren. Die Quellensuche besitzt einen Python-Fallback, falls `rg` im
Executor-Image fehlt.
## Bekannte Probleme des alten Hosts
- Systempartition vollständig gefüllt
- Datenpartition nahezu vollständig gefüllt
- etwa 1,27 TB Modelle, darunter Duplikate
- mehrere alte llama.cpp-Builds
- RX-Dienste trotz ausgebauter Karte
- aktivierte Benchmark-/Race-Dienste
- alte systemd-Overrides und Sicherungskopien
- unvollständiger großer Modelldownload
- zu viele MCP-Werkzeuge gleichzeitig im Kontext
Diese Punkte erklären den Neuaufbau, sind aber keine Bestandteile der neuen
Plattform.
Zusätzliche bekannte Sicherheitsabweichung: llama.cpp auf Port 8080 und XTTS
auf Port 8085 sind im alten Zustand breiter gebunden als im Zielsystem. Beim
Neuaufbau werden beide auf localhost begrenzt; Clients verwenden ausschließlich
den Router auf Port 8081.
### Deemix MCP
- Backend bleibt die bestehende Unraid-Instanz `192.168.1.2:6595`.
- Athena betreibt nur den API-Client `mike-ai-mcp-deemix`; kein zweites Deemix.
- Aktivierung über `/etc/mike-ai/deemix-mcp.env` (root-only, `0600`).
- Hermes und OpenWebUI nutzen das private Docker-Werkzeugnetz; kein zusätzlicher
VPN-Port und keine WireGuard-Änderung sind erforderlich.
docs/DISASTER_RECOVERY.md
-179
View File
@@ -1,179 +0,0 @@
# Disaster Recovery und Abnahme
## Definition „vollständig wiederhergestellt“
Eine Installation gilt erst dann als wiederhergestellt, wenn nicht nur Prozesse
laufen, sondern alle fachlichen Funktionen geprüft wurden.
## Phase A – Basissystem
- [ ] Betriebssystem und Kernel dokumentierter Stand
- [ ] Uhrzeit, Zeitzone und NTP korrekt
- [ ] Netzwerk nach Neustart automatisch verfügbar
- [ ] NVIDIA-Treiber geladen
- [ ] RTX und kompletter VRAM sichtbar
- [ ] System- und Modelllaufwerk korrekt gemountet
- [ ] mindestens 15 Prozent frei auf dem Systemlaufwerk
- [ ] Docker und Compose funktionieren
- [ ] keine RX- oder Benchmark-Altlast aktiviert
## Phase B – Textmodell
- [ ] llama.cpp entspricht dem festgelegten Commit
- [ ] Modelldateien stimmen mit SHA256 überein
- [ ] Fast startet mit 76.800 Kontext
- [ ] Medium startet mit 160.000 Kontext und ist Standard
- [ ] Large startet mit 192.000 Kontext
- [ ] Ultra startet mit 262.144 Kontext und bleibt text-only
- [ ] Uncensored startet mit 80.000 Kontext, 90:10 und MTP2
- [ ] GPU-/CPU-Verteilung entspricht den Profilen
- [ ] Fast erreicht den festgelegten Geschwindigkeitstoleranzbereich
- [ ] MTP funktioniert und verursacht keine Qualitätsregression
- [ ] Rolling-/Kontextverhalten ist bewusst definiert und getestet
## Phase C – Router
- [ ] Start ohne API-Key schlägt bewusst fehl
- [ ] `/health` bleibt bei Hotswap 200 und `/ready` wird vorübergehend 503
- [ ] geschützte Endpunkte liefern ohne Key 401
- [ ] Router-Key erscheint weder im Upstream noch im Journal
- [ ] `/status` meldet den richtigen Upstream
- [ ] `/v1/models` liefert fünf virtuelle Modelle
- [ ] `/fast`, `/medium`, `/large`, `/ultra` und `/uncensored` wechseln zuverlässig
- [ ] automatischer Wechsel über virtuellen Modellnamen funktioniert
- [ ] paralleler Wechsel wird sauber gesperrt
- [ ] Streaming funktioniert
- [ ] Tool Calls funktionieren
- [ ] Fehler sind OpenAI-kompatibel
- [ ] ein abgebrochener Client hinterlässt keinen blockierten Job
- [ ] erzwungener Routerabbruch wird aus Zustandsdatei sauber rekonstruiert
- [ ] fehlende/falsche Profilregistry verhindert falsche Readiness
## Phase D – Web und MCP
- [ ] OpenWebUI zeigt nur die fünf MikeAI-Arbeitsbereichsmodelle
- [ ] rohe `qwen-*`-Routermodelle sind ausgeblendet
- [ ] Medium ist die gespeicherte Standardauswahl
- [ ] Filter und Quick Actions sind allen fünf Presets zugeordnet
- [ ] native OpenWebUI-Websuche funktioniert ohne `web-local`; Auto Tool Selector wählt GitHub, Home
Assistant, ARR, Navidrome, Unraid read-only, Athena-Plattformwissen und
den Athena Operator korrekt
- [ ] normale Unterhaltung erhält kein MCP; reine Unraid-Abfragen erhalten nur
MUA read-only; ausdrücklich verlangte Unraid-Änderungen erhalten automatisch
MUA read-only plus Verwaltung
- [ ] MUA r019 oder neuer meldet `unraid_docker_update_verified_batch`; ein
Wiederholungstest mit aktuellem Image endet ohne Container-Neuerstellung
- [ ] MUA r020 oder neuer meldet `unraid_files_inventory`; ein lesender
Medienauftrag aktiviert nur MUA read-only und kann einen Sammlungsordner
plus dessen Dateinamen in zwei begrenzten Aufrufen erfassen
- [ ] eine synthetische CSV wird lokal ausgewertet; kein Webwerkzeug erhält Dateidaten
- [ ] ein rekursiver GitHub-Komplettbaum ist nicht als Werkzeug verfügbar
- [ ] der zweite identische Werkzeugaufruf wird gestoppt und eine Abschlussantwort erzeugt
- [ ] SearXNG und TinySearch gesund
- [ ] Websuche liefert kompakte, quellengebundene Ergebnisse
- [ ] `web_read` liest eine bekannte öffentliche Testseite ohne neue Suche
- [ ] `web_youtube` liefert mit `mode=latest` die neuesten Videos des offiziellen
The-Proper-People-Kanals samt Veröffentlichungszeit
- [ ] `web_youtube` trennt mit `content_type=long` und `content_type=short` die
jeweiligen YouTube-Tabs und setzt `content_type_verified=true`
- [ ] vier ähnliche erfolglose Suchvarianten werden serverseitig gestoppt
- [ ] GitHub- und Hugging-Face-Routing geprüft
- [ ] Home Assistant read-only Diagnose geprüft
- [ ] Home-Assistant-MCP löst `ha.casaderoll.de` im Container auf die private
`HOME_LAN_PROXY_IP` auf und `tools/list` antwortet über WireGuard
- [ ] ARR read-only Suche geprüft
- [ ] Navidrome-MCP gesund; 38 beziehungsweise mit Last.fm 45 Werkzeuge
- [ ] Navidrome-Schemas vollständig llama.cpp-kompatibel
- [ ] Navidrome ist nicht pauschal an jedes Modellprofil gebunden
- [ ] offizieller GitHub-MCP gesund; exakt drei read-only Repository-Werkzeuge
- [ ] `dev/verify_mcp_catalogs.sh` endet mit `MCP_CATALOG_SUITE_OK`
- [ ] GitHub-Token liegt nur in `/etc/mike-ai/github-mcp.env` (0600), nicht in OpenWebUI
- [ ] Unraid read-only Diagnose geprüft
- [ ] schreibende Werkzeuge standardmäßig nicht geladen; automatische Auswahl
gilt nicht als Änderungsfreigabe
- [ ] Tool-Schemas bleiben innerhalb des festgelegten Kontextbudgets
- [ ] kein Secret erscheint in Toolantworten oder Logs
- [ ] `PLATFORM_OVERVIEW.md`, `QWEN_OPERATOR_CONTEXT.md` und der Operator-
System-Prompt entsprechen dem wiederhergestellten Stand
- [ ] Platform-Context-Snapshot aktuell; offene Vorschläge und angewandte
Dokumentationsänderungen mit `athena_get_maintenance_status` geprüft
- [ ] Athena Operator und rootseitiger Executor gesund; Lesen und Preview
erfolgreich; falsches/abgelaufenes Ticket, Pfadausbruch, WireGuard-Stopp,
freie Befehle, SSH, Reboot und Shutdown in Negativtests verweigert
- [ ] Hermes-Profile Fast, Medium, Large, Ultra und Uncensored vorhanden;
`athena-operator` liegt im Standardprofil und in allen fünf Profilen
- [ ] falls `INSTALL_HERMES_WEBUI=true`: Community-WebUI auf VPN-Port 8787
gesund, Chat-Backend ist das bestehende Hermes-Gateway und weder Hermes
noch das aktive Qwen-Profil wurde dafür neu gestartet
- [ ] lokales Dokumentations-Overlay ist auch im privaten Git enthalten und
der Recovery-Koffer wurde danach neu erzeugt
## Phase E – Vision, Bild und Sprache
- [ ] neues Bild wird ohne Dienstneustart direkt vom aktiven Qwen analysiert
- [ ] Folgefrage bleibt im multimodalen Verlauf und löst keinen Hotswap aus
- [ ] Bilddaten werden größen- und URL-validiert
- [ ] Remote-/private Bild-URL wird abgewiesen und übergroße Data-URL blockiert
- [ ] llama.cpp-PID und aktives Profil bleiben bei Vision unverändert
- [ ] FLUX erzeugt Standard- und High-Bild
- [ ] Qwen-Profil wird nach FLUX wiederhergestellt
- [ ] Whisper transkribiert deutsche und englische Testdatei
- [ ] XTTS-v2 läuft ausschließlich auf der RTX 3060 und meldet `Annmarie Nele`
- [ ] TTS-Gateway erzeugt über den Router deutsche und englische WAV-/MP3-Ausgabe
- [ ] englische IT-Begriffe im deutschen Satz werden sprachlich segmentiert
- [ ] gestopptes XTTS fällt ohne Router-/OpenWebUI-Neustart auf Piper zurück
- [ ] Piper-Fallback und `piper-tts`-Version entsprechen der Installationskonfiguration
- [ ] STT/TTS blockieren das Textmodell nicht unzulässig
## Phase F – Sicherheitsprüfung
- [ ] alle Anwendungsports aus `VPN_SERVICE_PORTS.md` an der physischen
Hostadresse nicht erreichbar
- [ ] OpenWebUI, Router und alle gestarteten MCPs über die Fritz-VPN-Adresse
erreichbar
- [ ] gestopptes WireGuard-Gateway blockiert Container-Egress
- [ ] Hilfsports nur localhost
- [ ] Router nur aus erlaubtem Netz erreichbar
- [ ] Dienste laufen mit minimalen Rechten
- [ ] Environment-Dateien Modus 0600
- [ ] Athena Operator bietet strukturierte Abläufe und das breite Terminal;
Power sowie Athenas SSH/LAN/WireGuard/Firewall/Boot/Kernel/Mounts bleiben blockiert
- [ ] Schreibaktionen verlangen Vorschau und Approval Ticket
- [ ] Secret-Restore wurde ohne Klartextausgabe durchgeführt
- [ ] verschlüsseltes Recovery-Bundle liegt außerhalb von Athena
- [ ] age-Identität liegt getrennt vom Bundle und nicht auf Athena
## Phase G – Fachlicher Benchmark
Der gespeicherte Standardbenchmark wird mindestens mit Fast und Medium sowie
für Kontextgrenzen zusätzlich mit Large und Ultra sowie mit dem gesonderten
Uncensored-Sicherheitslauf ausgeführt:
- Home-Assistant-Automatisierung analysieren
- Logs lesen und Fehlerursache begründen
- sichere Korrektur vorschlagen
- Webrecherche mit Quellen durchführen
- Docker-/Unraid-Diagnose simulieren
- Tool-Limits, Halluzinationen und unnötige Aufrufe bewerten
Die neue Installation muss innerhalb einer vorher festgelegten Toleranz zur
Referenz liegen. Nur „Dienst läuft“ genügt nicht.
## Recovery-Protokoll
Für jeden Wiederaufbau werden festgehalten:
- Datum
- verwendeter Repository-Commit
- Modellmanifest-Version
- Hardware
- Dauer je Phase
- Abweichungen
- Testergebnis
- verantwortliche Freigabe
Erst nach Abschluss aller Pflichtpunkte darf der alte Host gelöscht oder als
Fallback außer Betrieb genommen werden.
Der ausführbare Ablauf steht in [BARE_METAL_RECOVERY.md](BARE_METAL_RECOVERY.md).
docs/EMERGENCY_UNI_ACCESS.md
-83
View File
@@ -1,83 +0,0 @@
# Notfallzugriff aus dem Universitätsnetz
## Zweck
Der normale Zugang zu Open WebUI und den MCP-Endpunkten erfolgt ausschließlich
über WireGuard. Falls vorübergehend ein administrativer Zugriff über die
Standortverbindung erforderlich ist, werden die KI-Ports **nicht** im
Universitätsnetz veröffentlicht. Stattdessen stellt ein kurzlebiger Proxy sie
nur auf Athenas Loopback-Adresse bereit; ein authentifizierter SSH-Tunnel bringt
sie verschlüsselt zum eigenen Rechner.
Dieser Weg eignet sich beispielsweise zur Diagnose eines gestörten VPN-Tunnels.
Er verändert das Fail-Closed-Egress nicht: Ist die Fritzbox nicht erreichbar,
funktionieren lokaler Chat und Administration, aber MCP-Zugriffe auf Heimnetz
und Internet bleiben absichtlich blockiert.
## 1. Auf Athena aktivieren
Per SSH auf Athena anmelden und als root ausführen:
```bash
mike-ai-emergency-access start
mike-ai-emergency-access status
```
Die Ausgabe darf ausschließlich Bindings mit `127.0.0.1` zeigen. Verwendet
werden:
| Lokaler Port auf Athena | Ziel |
|---:|---|
| 18080 | Open WebUI |
| 18090 | Web-MCP |
| 18091 | Home-Assistant-MCP |
| 18092 | ARR-MCP |
| 18093 | Unraid-MCP (read-only) |
Fehlende optionale MCP-Container werden übersprungen. Die Proxy-Container
verwenden kein neues Image, keine Secrets und keine zusätzlichen Rechte. Sie
besitzen keine Restart-Policy und verschwinden spätestens beim Hostneustart.
## 2. SSH-Tunnel auf dem eigenen Rechner öffnen
`<UNI-IP-ODER-DNS>` durch die aktuelle Standortadresse von Athena ersetzen:
```bash
ssh -N \
-L 18080:127.0.0.1:18080 \
-L 18090:127.0.0.1:18090 \
-L 18091:127.0.0.1:18091 \
-L 18092:127.0.0.1:18092 \
-L 18093:127.0.0.1:18093 \
-i ~/.ssh/athena_key root@<UNI-IP-ODER-DNS>
```
Das Terminal bleibt während der Nutzung geöffnet. Danach ist Open WebUI unter
`http://127.0.0.1:18080` erreichbar. Die MCP-URLs lauten entsprechend
`http://127.0.0.1:18090/mcp` bis `http://127.0.0.1:18093/mcp`.
## 3. Sofort wieder schließen
Den SSH-Tunnel mit `Ctrl+C` beenden und auf Athena ausführen:
```bash
mike-ai-emergency-access stop
mike-ai-emergency-access status
```
Zusätzlich prüfen:
```bash
ss -lnt | grep -E ':(18080|18090|18091|18092|18093) '
```
Nach `stop` darf dieser Befehl nichts mehr ausgeben. Port 8080 und 8081 bleiben
während des gesamten Vorgangs an der physischen Standortadresse geschlossen.
## Was ausdrücklich nicht gemacht wird
- kein Binding auf `0.0.0.0`
- keine direkte Freigabe von 8080/8081 im Universitätsnetz
- keine Änderung der Fail-Closed-Routingregeln
- kein Fallback der MCPs auf das Universitäts-Internet
- keine dauerhafte Notfallfreigabe und kein automatischer Neustart der Proxys
docs/GITHUB_MCP.md
-87
View File
@@ -1,87 +0,0 @@
# GitHub MCP: sicherer Lese- und Wartungsmodus
## Normalbetrieb
Athena startet den offiziellen GitHub MCP grundsätzlich im Nur-Lesen-Modus.
Sichtbar sind exakt:
- `search_repositories`
- `get_file_contents`
- `search_code`
`get_repository_tree` ist absichtlich nicht freigeschaltet: rekursive Bäume
können bei Monorepositories den kompletten Werkzeugkontext belegen. Der sichere
Weg ist eine gezielte Codesuche und anschließend das Lesen einzelner Dateien.
Der Token liegt ausschließlich in `/etc/mike-ai/github-mcp.env` (Modus 0600).
Er steht weder in Open WebUI noch in Git, der Dokumentation oder dem Platform
Context MCP. Der Container besitzt keinen Host-Port.
Status anzeigen:
```bash
sudo /opt/mike-ai/stack/platform/mcp/github-mcp-mode.sh status
```
## Bewusster Wartungstermin mit Schreibzugriff
Wenn Dateien in einem eigenen Repository geändert werden sollen, aktiviert der
Administrator den begrenzten Wartungsmodus:
```bash
sudo /opt/mike-ai/stack/platform/mcp/github-mcp-mode.sh maintenance --confirm
```
Zusätzlich zu den Lesewerkzeugen werden nur diese Operationen angeboten:
- Branches auflisten und einen neuen Branch anlegen
- eine oder mehrere Dateien committen
- einen Pull Request anlegen
Absichtlich fehlen Löschen, Mergen, Repository-Erstellung, Workflow-Ausführung,
Issue-Veränderungen und administrative Werkzeuge. Trotzdem ist dies echter
Schreibzugriff. Vor jeder Änderung muss das Modell den aktuellen Dateiinhalt
lesen, auf einem neuen Branch arbeiten und Ziel, Dateien und Wirkung nennen.
Nach der Arbeit sofort zurückschalten:
```bash
sudo /opt/mike-ai/stack/platform/mcp/github-mcp-mode.sh read
```
Beide Umschaltungen starten nur den GitHub-MCP-Container neu und danach kurz
das Open-WebUI-Backend, damit dessen Werkzeugcache sicher zum aktiven Modus
passt. LLM-Profile, Router, VPN und andere MCPs werden nicht neu gestartet.
## Token-Rechte
Die serverseitige Werkzeugliste ersetzt keine saubere Tokenbegrenzung. Für den
Normalbetrieb ist ein nur lesender Fine-grained PAT ideal. Ein Token, der auch
schreiben darf, sollte nur Zugriff auf ausdrücklich ausgewählte Repositories und
den geringsten benötigten `Contents`-Umfang erhalten. Geschützte Hauptbranches
und verpflichtende Pull Requests bilden die zweite Schutzschicht.
Nach Tokenwechsel oder Rechteänderung:
```bash
sudo /opt/mike-ai/stack/platform/mcp/github-mcp-mode.sh read
```
## Fehlerbehebung
`Failed to connect to MCP server 'github-local'` war am 23. August 2026 kein
Tokenfehler. Supergateway beantwortete den regulären MCP-Handshake von Open
WebUI fehlerhaft. Produktiv wird deshalb der offizielle GitHub MCP 1.10.1 über
`mcp-proxy` 0.12.0 bereitgestellt. Der Pfad wurde mit Open WebUIs eigenem
Python-MCP-Client und einer echten öffentlichen Repositorysuche geprüft.
Falls ein Werkzeug stattdessen einen Code für `github.com/login/device`
ausgibt, ist der PAT nicht im GitHub-stdio-Unterprozess angekommen. Der
produktive Proxy verwendet deshalb ausdrücklich `--pass-environment`. Der PAT
darf nicht in den Chat kopiert und die Geräteanmeldung nicht als Dauerlösung
verwendet werden.
Der Normalmodus ist Teil des Installationsskripts. Skript, Compose-Override und
diese Anleitung liegen im Git-Repository und werden vom Recovery-Koffer
mitgeführt. Das Platform Context MCP kann diese Anleitung lesen, erhält aber
weder Token noch die Fähigkeit, den Modus selbst unbemerkt umzuschalten.
docs/INSTALLATION.md
-221
View File
@@ -1,221 +0,0 @@
# Installation auf einem frischen Debian-Host
Der automatisierte Weg ist `install.sh`. Das Skript ist für **Debian 12/13
amd64** gedacht, installiert Docker CE, den aktuellen Compute-only-NVIDIA-Treiber
mit offenen Kernelmodulen aus dem offiziellen NVIDIA-Repository, das
NVIDIA-Container-Toolkit,
WireGuard, baut llama.cpp reproduzierbar, lädt Modelle mit SHA256-Prüfung und
startet den Stack.
## Vorher klären
1. Die Universität muss den ausgehenden WireGuard-Tunnel erlauben.
2. Heimnetz, Universitätsnetz und Docker-Netz dürfen sich nicht überschneiden.
3. In der Fritzbox eine Konfiguration für **einen einzelnen Client** exportieren.
4. Der Fritzbox-Zugang muss Heimnetz und gewünschten Internetverkehr erlauben.
5. Das private Repository muss auf dem neuen Host lesbar sein.
## Debian installieren
- Debian 13 minimal, amd64, OpenSSH-Server, kein Desktop erforderlich.
- Einen normalen Administrationsbenutzer mit sudo anlegen.
- Optional bei physischem Fremdzugriff: LUKS-Verschlüsselung.
- BIOS: Above 4G Decoding aktiv; beide GPUs sichtbar machen.
## Konfiguration
```bash
git clone <PRIVATE-REPOSITORY-URL> AI-Profile-Router
cd AI-Profile-Router
cp config/install.env.example config/install.env
chmod 600 config/install.env
editor config/install.env
```
Mindestens `ADMIN_USER`, Netzwerkschnittstellen, GPU-Zuordnung und Modellwerte
prüfen. Die Fritzbox-Datei vor dem Start root-only ablegen:
```bash
sudo install -d -m 700 /etc/mike-ai/wireguard
sudo install -m 600 fritz-athena.conf /etc/mike-ai/wireguard/fritz-athena.conf
```
Router- und WebUI-Schlüssel werden lokal erzeugt und nur unter `/etc/mike-ai`
gespeichert. Der Installer gibt keine privaten WireGuard-Werte aus.
## Installation starten
```bash
sudo ./install.sh --config config/install.env
```
Wenn erstmals ein NVIDIA-Treiber installiert wurde, endet das Skript bewusst
mit Code 20. Dann neu starten und denselben Befehl erneut ausführen. Das Skript
ist auf Wiederholung ausgelegt und löscht keine vorhandenen Modelldateien.
Beim ersten Stackstart lädt der interne Piper-Container die konfigurierte
deutsche Stimme in sein persistentes Volume. Dadurch kann seine erste
Bereitschaft je nach Internetverbindung etwas länger dauern.
Der Compose-Start wartet auf einen aktuellen WireGuard-Handshake. API-Schlüssel
werden nicht ausgegeben. Sie liegen root-only unter `/etc/mike-ai`.
## Ergebnis und Abnahme
- Open WebUI: `http://<WIREGUARD-IP>:8080`
- Router: `http://<WIREGUARD-IP>:8081`
- Hermes Dashboard: `http://<WIREGUARD-IP>:9119`
- Hermes API: `http://<WIREGUARD-IP>:8642`
- SSH fallback: `ssh root@<WIREGUARD-IP>` (key-only, forwarded to host sshd)
- llama.cpp-WebUI: absichtlich deaktiviert und nicht veröffentlicht
```bash
sudo systemctl status mike-ai-container-vpn-guard
sudo docker inspect -f '{{.State.Health.Status}}' mike-ai-wireguard-gateway
sudo docker compose --env-file /etc/mike-ai/stack.env \
-f /opt/mike-ai/stack/compose.yaml ps
curl http://<WIREGUARD-IP>:8081/health
curl http://<WIREGUARD-IP>:8642/health
ssh -o BatchMode=yes root@<WIREGUARD-IP> true
```
Hermes verwendet standardmäßig `qwen-medium` mit 160K Kontext und dieselbe
Router-API wie OpenWebUI. Das Dashboard meldet sich mit Benutzer `michael` an;
das zufällig erzeugte Kennwort wird ausschließlich lokal angezeigt:
```bash
sudo cat /etc/mike-ai/hermes-dashboard-password
```
Der Schlüssel der Agent-API liegt entsprechend unter
`/etc/mike-ai/hermes-api-key`. Beide Werte gehören weder in Git noch in Chats.
Hermes' lokales Terminal sieht nur `/data/hermes/workspace` im Container. Für
Athena und Unraid verwendet es die dokumentierten Operator-/MUA-MCPs.
Ein Startwächter beendet den Container absichtlich, falls diese verwaltete
Konfiguration nicht lesbar ist oder auf einen anderen Provider als den lokalen
Router zeigt. Dadurch darf ein Rechtefehler nicht auf Hermes' Cloud-Standard
zurückfallen.
Der SSH-Fallback lauscht ausschließlich auf der IPv4-Adresse von `wg0` im
WireGuard-Gateway-Container. Er wird nicht als Docker-Port auf dem
Standort-Interface veröffentlicht. Das Gateway leitet die Verbindung an den
hostseitigen Gateway-Endpunkt des festen `frontend`-Netzes weiter; Anmeldung,
Schlüsselprüfung und Protokollierung erfolgen weiterhin durch den normalen
OpenSSH-Dienst des Hosts.
Die TTS-Verbindung wird für eine frische Open-WebUI-Datenbank automatisch als
OpenAI-kompatibler Audio-Endpunkt des Routers vorbelegt. Der Router reicht sie
intern an das TTS-Gateway weiter. Primär spricht XTTS-v2 mit `Annmarie Nele`
auf der RTX 3060; bei Fehlern oder Queue-Timeout übernimmt Piper auf der CPU.
Der Port 8085 wird nicht am Host veröffentlicht. Ein
Restore setzt zusätzlich die vier persistenten Audiofelder gezielt neu, damit
alte Werte wie `tts-1` oder `coral` die Compose-Vorgaben nicht überstimmen.
`TTS_CODE_SWITCH_ENABLED=false` hält gemischte Antworten als zusammenhängende
deutsche Satzblöcke. Einzelne englische Fachbegriffe werden damit zwar deutsch
ausgesprochen, die Ausgabe bleibt jedoch flüssig und verständlich. Reine
englische Texte erkennt das Gateway weiterhin automatisch. Ein Ende-zu-Ende-Test
ohne Ausgabe des API-Schlüssels:
Für die Sprachausgabe normalisiert das Gateway außerdem Datumsangaben,
Temperaturen, Prozentwerte, Postleitzahlen und Domains. Beispielsweise wird
`22° / 10°` als „Höchstwert 22 Grad, Tiefstwert 10 Grad“ und `wetter.com` als
„Wetter Punkt C O M“ gesprochen. Die deutsche Endung `.de` bleibt natürlich
gesprochen. Die sichtbare Chatantwort wird nicht verändert.
```bash
set -a; source /etc/mike-ai/stack.env; set +a
curl -fsS http://127.0.0.1:8081/v1/audio/speech \
-H "Authorization: Bearer $ROUTER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"piper","voice":"alloy","input":"Hallo von Athena.","response_format":"mp3"}' \
-o /tmp/athena-tts-test.mp3
```
Der beibehaltene API-Name `piper/alloy` ist eine Kompatibilitätsschnittstelle;
bei gesundem XTTS stammt die Ausgabe von `Annmarie Nele`. Der interne Status
des TTS-Gateways nennt `last_backend`, `primary_ready`, `fallback_ready` und
die Zahl der Piper-Rückfälle. Ein Fallback-Test stoppt ausschließlich XTTS,
erzeugt einen synthetischen Satz über denselben Router-Endpunkt und startet
XTTS anschließend wieder. OpenWebUI und Router müssen dafür nicht geändert
oder neu gestartet werden.
Zusätzlich prüfen: Standort-LAN sieht keine KI-Ports; Heimnetz erreicht beide;
gestopptes VPN-Gateway lässt KI-Container nicht ins Internet; jeder Profilwechsel
startet exakt einen llama-Container; Text, Tool Call, Bild und Sprachausgabe funktionieren.
Nach dem ersten Anlegen des OpenWebUI-Administrators werden Filter, Quick
Actions und die fünf Arbeitsbereichsmodelle reproduzierbar eingespielt:
```bash
sudo /opt/mike-ai/stack/platform/openwebui/install-filters.sh
sudo /opt/mike-ai/stack/platform/openwebui/install-models.sh
```
Danach sind nur die fünf benannten MikeAI-Presets sichtbar; die rohen
Router-Aliase sind ausgeblendet und Medium ist die Standardauswahl. Beide
Skripte sichern die OpenWebUI-Datenbank vor jeder Änderung. Der Modellinstaller
synchronisiert außerdem OpenWebUIs persistente OpenAI-kompatible Verbindung mit
dem internen Router und dessen aktuellem Schlüssel. Das ist erforderlich, weil
persistente Providerwerte nach einer Schlüsselrotation Vorrang vor den
Container-Umgebungsvariablen haben.
Der Filterinstaller richtet außerdem die lokalen gesprochenen
Werkzeugbestätigungen ein. Die vorgerenderten Ansagen werden über
`/static/tool-status/` read-only ausgeliefert und nur bei aktivierter
automatischer Sprachausgabe abgespielt. Zur Abnahme eine Websuche und eine
Unraid-Abfrage auslösen: Vor längeren Aufrufen muss genau eine kurze passende
Ansage kommen; bei ausgeschalteter automatischer Sprachausgabe bleibt sie aus.
Der Modellinstaller setzt außerdem für den ermittelten OpenWebUI-Benutzer das
native Chat-Hintergrundbild `/static/midnight-aurora.svg`. Das Bild wird durch
Compose read-only eingebunden. `custom.css` verändert bewusst nicht mehr die
strukturellen Chat-Layer, damit OpenWebUIs eigene Bildfläche, Kontrast-Overlay
und Mobilansicht funktionieren. Ein bestehender Benutzer kann denselben Wert
auch unter **Einstellungen → Oberfläche → Chat Background Image** ändern.
## Werkzeug-Container
Der Installer startet Websuche automatisch in einem privaten Docker-Netz.
Weitere Bereiche werden nur aktiviert, wenn ihre root-only Konfiguration schon
vorhanden ist:
```text
/etc/mike-ai/homeassistant-admin-mcp.env
/etc/mike-ai/arr-mcp.env
/etc/mike-ai/navidrome-mcp.env
/etc/mike-ai/mua-mcp.env
```
Die MUA-Datei wird nach `config/mua-mcp.env.example` angelegt und mit Modus
`0600` geschützt. Sie verbindet Open WebUI direkt mit dem MUA-Plugin auf dem
Unraid-HomeServer. Unraids GraphQL-API wird nicht benötigt und soll deaktiviert
bleiben.
Nach dem Nachreichen einer Datei genügt:
```bash
sudo /opt/mike-ai/stack/platform/mcp/install-tools.sh
```
Auf einer frischen Open-WebUI-Datenbank werden die internen MCP-Adressen über
`TOOL_SERVER_CONNECTIONS` vorbelegt. Bei einer übernommenen Datenbank müssen
die Einträge einmal unter **Admin-Einstellungen → Externe Werkzeuge** geprüft
oder importiert werden. Die Endpunkte stehen in `platform/mcp/README.md`.
Kein MCP-Port wird auf der physischen Universitätsadresse veröffentlicht.
OpenWebUI nutzt intern weiterhin die Docker-Namen; Pi, Hermes und andere
Clients greifen direkt über die festen WireGuard-Adressen aus
[VPN_SERVICE_PORTS.md](VPN_SERVICE_PORTS.md) zu. Ein zusätzliches MCP-Gateway
oder ein weiterer Auth-Layer innerhalb des Heim-VPNs ist nicht vorgesehen.
Die vollständige Wiederherstellung einschließlich OpenWebUI, MCP-Secrets und
Navidrome/Last.fm ist unter
[BARE_METAL_RECOVERY.md](BARE_METAL_RECOVERY.md) dokumentiert und durch
ausführbare Backup-/Restore-Skripte abgebildet.
Die Standardkonfiguration lädt IQ4-MIX für Fast, IQ4_XS Pure für Medium,
Large und Ultra sowie Abliterated Q4_K_M für Uncensored aus den dokumentierten Hugging-Face-Repositories. URLs,
Dateinamen und SHA256 stehen vollständig in `config/install.env.example`.
Der Installer lädt jede identische Datei nur einmal und löscht vorhandene
Modelle nicht.
Open-WebUI-Daten liegen in einem Docker-Volume und müssen separat gesichert
werden. Geheimnisse und Chatdaten gehören nie in Git.
docs/MIGRATION.md
-80
View File
@@ -1,80 +0,0 @@
# Migration vom bestehenden Host
## Behalten
- Qwen3.8-27B IQ4-MIX und das getestete MTP2-Profil
- IQ4_XS Pure für Medium
- Abliterated Q4_K_M und passender F16-mmproj für Uncensored
- BF16-`mmproj` für die integrierte Vision aller Qwen-Profile
- festgeschriebener llama.cpp-Commit
- Router, Piper-TTS, Whisper und Websuche
- spezialisierte MCPs nach Sicherheitsprofil
- relevante Benchmarkresultate
## Nicht übernehmen
- RX-470-Dienste
- doppelte Whisper-Server
- automatisch aktivierte Modellrennen und Benchmarks
- unvollständige Modelldownloads
- alte llama.cpp-/BeeLlama-Testbuilds
- alte systemd-Backups
- Caches und generierte Medien
- doppelte oder klar unterlegene Modelle
## Reihenfolge
1. Repositories und verschlüsselte Konfiguration sichern.
2. Modellmanifest mit Dateigrößen und SHA256 erstellen.
3. Neuen Host installieren und Speicherlayout festlegen.
4. NVIDIA-Treiber und CUDA verifizieren.
5. Festgeschriebenen llama.cpp-Commit bauen.
6. nur die benötigten Modelle übertragen und Hashes prüfen.
7. Fast-Profil ohne MCP starten und testen.
8. Medium, Large, Ultra und Uncensored einzeln testen.
9. Router installieren und Profilwechsel testen.
10. Web, HA, ARR und Unraid nacheinander hinzufügen.
11. Piper-TTS prüfen; optional STT ergänzen und den Projektor für integrierte Vision prüfen.
12. Standardbenchmark und Sicherheitsprüfung ausführen.
13. Erst danach Clients umstellen.
## Referenz-Backup automatisiert einspielen
Nach einem erfolgreichen Lauf von `install.sh` kann eine Sicherung des alten
Referenzhosts gezielt importiert werden:
```bash
sudo ./platform/migration/restore-reference-backup.sh \
/data/ki-migration-backup-YYYYMMDD
```
Das Skript prüft zuerst die Archiv-Hashes und übernimmt ausschließlich:
- die persistente OpenWebUI-Datenbank samt Einstellungen und Uploads,
- das zur Datenbank passende, gesicherte OpenWebUI-Container-Image,
- den dazugehörigen WebUI- und Router-Schlüssel,
- die freigegebenen HA-, ARR- und MUA-/Unraid-Secrets.
Es übernimmt bewusst **keine** alten Compose-Dateien, Routerprofile,
Experimentdienste oder `.before-*`-Altstände. Vor dem Ersetzen des frischen
OpenWebUI-Volumes wird unter `/data/open-webui-before-restore-*.tar.gz` eine
Rückfallsicherung erstellt. Secret-Werte werden nicht ausgegeben.
OpenWebUI-Datenbanken sind nicht beliebig vor- oder rückwärtskompatibel. Das
Restore-Skript lädt deshalb bewusst das im Backup inventarisierte Original-
Image, versieht es lokal mit dem Tag `mike-ai/openwebui:reference` und trägt
diesen Tag sowohl in `stack.env` als auch – falls vorhanden – in
`/root/mike-ai-install.env` ein. Dadurch bleibt auch ein späterer, idempotenter
Installerlauf versionsgleich. Ein Upgrade auf eine neuere OpenWebUI-Version
erfolgt erst danach kontrolliert und mit einer eigenen Datenbanksicherung.
Falls ein älteres Image-Archiv trotz seines Namens das OpenWebUI-Image nicht
enthält, verwendet das Skript ausschließlich den im Docker-Inventar gesicherten
unveränderlichen Registry-Digest. Es fällt niemals auf `latest` zurück.
Da lokale Docker-Image-IDs beim Wiederherstellen von einem Registry-Digest
abweichen können, verifiziert es zusätzlich die gesicherte OCI-Build-Revision.
Nach dem Datenimport wendet es außerdem die im Repository versionierten
OpenWebUI-Filter erneut an. Dadurch bleiben auch deren Prioritäten unabhängig
vom Alter der Datenbanksicherung reproduzierbar.
Der alte Host bleibt bis zum bestandenen Abnahmetest unverändert und dient nur
als Referenz. Es werden keine Caches oder unbekannten Altverzeichnisse kopiert.
docs/NEW_HOST_ROADMAP.md
-64
View File
@@ -1,64 +0,0 @@
# Roadmap: sauberer KI-Host
## Phase 0 – Entscheidungen und Freigaben
- VPN-Nutzung mit der Universität abstimmen.
- Eindeutige Netze und Heim-WireGuard-Peer festlegen.
- Festplattenverschlüsselung und Remote-Unlock entscheiden.
- Repository- und Secret-Backup prüfen.
## Phase 1 – Grundsystem
- Debian 13 minimal und OpenSSH installieren.
- Firmware/BIOS und beide NVIDIA-Karten prüfen.
- Updates, Zeitsynchronisation und administrativen Zugang testen.
## Phase 2 – automatischer Bootstrap
- `config/install.env` ausfüllen.
- `install.sh` ausführen, bei Treiberinstallation neu starten und wiederholen.
- WireGuard-Peer zuhause ergänzen.
- Docker-, GPU- und Fail-Closed-Netztest bestehen.
## Phase 3 – Inferenz abnehmen
- Fast/Medium/Long mit derselben Testserie messen.
- Kontext, Prompt-Speed, Ausgabe-Speed und VRAM dokumentieren.
- RTX 3060 zuerst nur im Experimentalprofil testen.
- Erst nach Qualitäts- und Geschwindigkeitsvergleich Produktionswerte ändern.
## Phase 4 – optionale Fähigkeiten
- Zentrale MCP-Werkzeugebene gemäß `ARCHITECTURE.md` aufbauen.
- Schlanken `mcp-gateway` nur über WireGuard veröffentlichen.
- `web-mcp` als unabhängigen Standard-Werkzeugcontainer betreiben.
- Home Assistant als getrennte Read-/Write-Instanzen desselben Images.
- Den vorhandenen kompakten `homeassistant-admin-mcp` zum zentralen
Streamable-HTTP-Werkzeugcontainer ausbauen. Er soll dem Modell kleine,
eindeutige Werkzeuge anbieten und den nativen Home-Assistant-MCP intern als
Datenquelle beziehungsweise Fallback verwenden, statt dessen sehr großen
Werkzeugkatalog direkt an jedes Modell durchzureichen.
- YAML-Unterstützung für Home Assistant ergänzen: zunächst lesen und
validieren; Änderungen ausschließlich über Diff/Vorschau, Sicherung,
Konfigurationsprüfung und explizite Freigabe. Keine freie Host-Shell und kein
ungeprüftes Überschreiben von Konfigurationsdateien.
- Den Admin-MCP anschließend gemeinsam für Open WebUI, Hermes und weitere
Clients anbieten; Read-only und Write/Approval bleiben getrennte Profile.
- ARR als getrennte Read-/Write-Instanzen mit Preview/Approval.
- Unraid-Diagnose und bewusst aktivierbare Administration trennen.
- Terminal ausschließlich als isolierten `sandbox-mcp`, nie als Host-Shell.
- Open WebUI, Hermes und weitere Clients mit denselben zentralen Endpunkten
verbinden und pro Chat nur benötigte Werkzeuggruppen aktivieren.
- Piper-TTS als eigener interner CPU-Container; Whisper oder Bildgenerierung
bei Bedarf ebenfalls jeweils als eigener Container.
## Phase 5 – Betrieb
- Open-WebUI-Volume, Konfigurationen und Secrets verschlüsselt sichern.
- Image- und llama.cpp-Upgrades im Experimentalprofil testen.
- Logs ohne Prompts/Secrets, Metriken für GPU, RAM und Tokenraten.
- Recovery auf leerem Testsystem regelmäßig proben.
Fertig ist der Host erst, wenn er sich aus Repository und Secret-Backup neu
erzeugen lässt, das Uni-Netz keine KI-Ports sieht, ein Tunnelverlust
fail-closed ist und alle drei Profile den Standardbenchmark bestehen.
docs/OPERATIONS.md
-267
View File
@@ -1,267 +0,0 @@
# Betrieb
## OpenWebUI-Filter und Stabilitätsschutz
Die versionierten Filter liegen unter `platform/openwebui/filters/`. Ihre
Reihenfolge ist absichtlich festgelegt:
1. `Reasoning Default Off`, Priorität 10: setzt jeden Request zunächst auf
`reasoning_effort=none`.
2. `Thinking`, Priorität 20: läuft nur bei aktiviertem Brain-Schalter und
überschreibt den Standard mit Low, Medium oder High.
3. `MikeAI Auto Tool Selector`, Priorität 25: betrachtet ausschließlich die
jüngste Nutzernachricht, hält die native allgemeine Websuche verfügbar und
ergänzt die passenden MCP-Domänen. Er erkennt GitHub, Home Assistant, Sonarr/Radarr, Navidrome,
Unraid-Diagnose und Athena-Plattformwissen. Manuell gewählte Werkzeuge
bleiben erhalten. Bei einer ausdrücklich verlangten Unraid-Änderung werden
MUA-Diagnose und -Verwaltung gemeinsam bereitgestellt; reine Statusfragen
bleiben read-only. Docker-Updates verwenden MUA r019 gebündelt, vergleichen
echte Image-IDs und erhalten den Laufzustand. Die Auswahl eines MCP ist
ausdrücklich keine Freigabe für eine andere Zustandsänderung.
Medienbestandsprüfungen verwenden ab MUA r020 zuerst eine gezielte
Verzeichnissuche und danach ein Inventar des exakten relativen Pfads mit
`unraid_files_inventory`; das allgemeine Athena-Terminal bleibt Fallback für
neue Aufgaben, die kein Fachwerkzeug abdeckt.
4. `MikeAI Stability Guard`, Priorität 30: begrenzt einzelne und gesamte
Werkzeugresultate, verdichtet bei Bedarf zuerst alte Tool-Ausgaben und
Dialogteile und stoppt identische beziehungsweise ausufernde Tool-Schleifen.
5. `MikeAI Secret Redaction`, Priorität 40: entfernt übliche API-Keys, Tokens,
Passwörter, JWTs und private Schlüssel aus Tool-Ergebnissen, bevor sie das
Modell erreichen, sowie aus fertigen Modellantworten. Nutzereingaben und
Authentifizierungswege werden nicht verändert. Offensichtliche
Dokumentationsplatzhalter, Beispielwerte und Dateipfade bleiben sichtbar.
Eine Statusmeldung nennt nur Trefferzahl, sichere Kategorie und Ursprung
(Werkzeugausgabe oder Modellantwort); der erkannte Wert wird weder angezeigt
noch protokolliert.
6. `MikeAI Spoken Tool Status`, Priorität 80: erkennt den ersten echten
Werkzeugaufruf eines Antwortlaufs und löst im Browser genau eine kurze,
passende Ansage für Web, Unraid, Home Assistant, Medienverwaltung oder
sonstige Werkzeuge aus. Die fünf MP3-Clips sind vorgerendert und liegen
unter `platform/openwebui/theme/tool-status/`; dadurch blockiert die Ansage
weder XTTS noch das Werkzeug. Sie wird nur abgespielt, wenn der Benutzer in
OpenWebUI die automatische Sprachausgabe aktiviert hat. Endet ein sehr
schneller Lauf innerhalb der kurzen Wartezeit, wird die Ansage verworfen.
7. `MikeAI Local Performance Metrics`, Priorität 90: erfasst nach Abschluss
ausschließlich technische Zahlen wie Laufzeit, Tokenzähler, Token/s und
Tool-Anzahl. Nutzer-, Chat- und Nachrichten-IDs sowie sämtliche Textinhalte
werden weder geschrieben noch gehasht gespeichert.
OpenWebUI sortiert kleinere Prioritäten zuerst. Nach dem ersten Anlegen eines
Admin-Benutzers oder nach einer Datenwiederherstellung werden alle Filter mit
einer vorherigen Datenbanksicherung installiert beziehungsweise aktualisiert:
```bash
sudo /opt/mike-ai/stack/platform/openwebui/install-filters.sh
```
Die sichtbaren Arbeitsbereichsmodelle und die versteckten Router-Aliase werden
separat und ebenfalls mit vorheriger Datenbanksicherung installiert:
```bash
sudo /opt/mike-ai/stack/platform/openwebui/install-models.sh
```
Dadurch erscheinen ausschließlich `MikeAI · Fast`, `MikeAI · Medium`,
`MikeAI · Large`, `MikeAI · Ultra` und `MikeAI · Uncensored`. Medium ist die Standardauswahl. Alle
fünf erhalten die geprüften Filter und Quick Actions sowie Piper-Stimme
`alloy`. Vision ist bei Fast, Medium, Large und Uncensored aktiviert; Ultra bleibt
bewusst text-only. Bildgenerierung wird erst als Fähigkeit freigeschaltet,
wenn ein echter Generator-Worker im Stack aktiv ist. Kein MCP ist statisch an
jedes Profil gebunden. Der Auto Tool Selector stellt nur die zur jüngsten
Anfrage passenden Werkzeuge bereit, damit irrelevante Schemas weder Kontext
verbrauchen noch die Werkzeugwahl des Modells verschlechtern. Eine manuelle
Auswahl im Chat bleibt zusätzlich möglich.
Die Auswahl arbeitet bewusst regelbasiert und lokal. Sie sendet keine Texte an
einen Klassifizierungsdienst, speichert keine Prompts und führt selbst keine
Werkzeugaktion aus. Erkennt sie keine eindeutige Absicht, wird kein MCP
automatisch ergänzt. Schreibende oder kritische Rechte werden weiterhin durch
das jeweilige MCP, Bestätigungsregeln und die manuelle MUA-Auswahl begrenzt.
Alle fünf Modelle erhalten außerdem dieselbe Evidenzregel: Aussagen über
aktuelle externe oder Systemzustände benötigen im aktuellen Turn einen
erfolgreichen Aufruf des zuständigen Fachwerkzeugs. Task-Verwaltung zählt nicht
als Datenquelle und wird für einzelne Fragen, Nachschlageaufgaben, Diagnosen
oder Dateiauswertungen nicht verwendet. Fehlt das Werkzeug oder schlägt es fehl, muss das Modell die
fehlende Verifikation offen nennen, statt Werte oder Diagnosen zu erfinden.
Bei mehreren Administratoren muss der gewünschte Eigentümer explizit über
`OPENWEBUI_FILTER_OWNER_ID` gesetzt werden. Das Skript liest oder verändert
keine Chats. Es deaktiviert zugleich global die automatisch erzeugten
Folgefragen (`task.follow_up.enable=false`). Dieselbe Vorgabe steht zusätzlich
als Container-Umgebungswert im Compose-Stack, damit bereits eine frische
OpenWebUI-Datenbank ohne Folgefragen startet.
Der Stabilitätsschutz kennt die fünf Profilgrenzen 76.800, 80.000, 160.000,
192.000 und 262.144 Token. Für unbekannte Modelle gilt Medium (160.000) als sichere
Vorgabe. Er reserviert Ausgabetoken und greift vor der harten llama.cpp-Grenze
ein. Bilder bleiben unangetastet; JSON-Werkzeugschemas werden niemals
abgeschnitten. Sind allein die ausgewählten Schemas zu groß, wird der
Werkzeugzugriff nur für diesen Schritt deaktiviert und das Modell erhält eine
eindeutige Abschlussanweisung.
Allgemeine Webrecherche läuft nativ über Open WebUIs `search_web` und
`fetch_url`; TinySearch ist der portable MCP-Weg für andere Clients. Die
frühere eigene Web-Fassade ist nur noch Rollback. Pro Antwort sind 48 interne
Runden und höchstens 40 tatsächliche Werkzeugausführungen möglich. Je
Werkzeugname sind zwölf Aufrufe möglich; eine identische Signatur darf einmal
wiederholt werden und wird beim dritten Versuch gestoppt. Ein Resultat ist auf
12.000 und alle Resultate zusammen auf 64.000 Zeichen begrenzt.
`install-filters.sh` setzt die schlüssellose DuckDuckGo-Suche dabei
reproduzierbar aktiv (fünf Treffer, maximal drei parallele Abrufe).
CSV-, TSV-, Excel- und ODS-Dateien werden ausschließlich lokal verarbeitet.
Die Profile aktivieren dafür den eingebauten Python-Code-Interpreter und die
nativen Dateizugriffswerkzeuge. Tabellen werden nicht als Knowledge/RAG-Text
behandelt; Web- und Web-MCP-Werkzeuge sind für private Tabellendaten gesperrt.
Der Home-Assistant-Relay behält `https://ha.casaderoll.de` als TLS- und
Hostnamen, löst ihn innerhalb des Containers aber über `extra_hosts` auf den
privaten Reverse Proxy `${HOME_LAN_PROXY_IP:-192.168.1.2}` auf. Damit fließt der
MCP-Verkehr über WireGuard ins Heimnetz und nicht über die öffentliche
Fritzbox-Adresse. Bei einer abweichenden Heimserver-IP wird nur
`HOME_LAN_PROXY_IP` in `/etc/mike-ai/stack.env` angepasst.
Nach Installation, Update oder Recovery prüft der rein lesende Katalog-TÜV
alle laufenden MCPs auf Handshake, Werkzeuganzahl, Schema-Größe, ungültige
Regex-Muster und verbotene GitHub-Komplettbäume. Er ruft dabei kein fachliches
Werkzeug auf und liest keine Chats oder Secrets:
```bash
sudo /opt/mike-ai/stack/dev/verify_mcp_catalogs.sh
```
Die rotierende, inhaltsfreie Metrikdatei liegt im persistenten
OpenWebUI-Volume unter `mike-ai-request-metrics.jsonl` (maximal 5 MiB plus eine
Rotation). Sie darf für Benchmarks ausgewertet werden, ohne Chats auszulesen.
Die Werkzeugansagen enthalten weder Prompt- noch Ergebnistext und werden nicht
in die Unterhaltung oder den Modellkontext geschrieben. Der lokale
OpenWebUI-Browser-Event prüft die persönliche Einstellung
`responseAutoPlayback` über denselben Browser-Login. Ein Fehler, eine
Browser-Autoplay-Sperre oder ein fehlender Clip bleibt folgenlos für den Chat.
## Aktionen an Modellantworten
Die globale Action `MikeAI Quick Actions` ergänzt die Nachrichtenleiste um:
- `Kurzfassung`, `Als Checkliste`, `Technische Diagnose` und
`Unsicherheiten prüfen`: jeweils ein bewusster zusätzlicher lokaler
Modellaufruf, dessen Ergebnis unter der gewählten Antwort ergänzt wird.
- `Mit Thinking verbessern`: lokale erneute Prüfung mit Medium-Reasoning und
festem Thinking-Budget; Werkzeuge werden dabei nicht injiziert.
- `Quellen prüfen`: erstellt lokal eine knappe Suchanfrage, ruft ausschließlich
den internen Web-MCP auf und lässt Qwen die Antwort gegen dessen begrenzte,
als unvertrauenswürdig markierte Belege prüfen.
- `Markdown kopieren`: kopiert den gewählten Antworttext im aktiven Browser
ohne Modellaufruf und ohne serverseitige Datei.
Die Aktionen schreiben nicht in Git oder Zielsysteme und schalten keine
Routerprofile um. Action-Funktionen laufen mit Serverrechten; deshalb bleibt
der geprüfte Quellcode Bestandteil dieses Repositorys und wird nicht aus dem
Community Store nachgeladen.
## Profile
| Profil | Virtuelles Modell | Kontext | Zweck |
|---|---|---:|---|
| Fast | `qwen-fast` | 76.800 | Alltag, Agenten, hohe Geschwindigkeit, integrierte Vision |
| Medium **(Standard)** | `qwen-medium` | 160.000 | IQ4_XS Pure, beide GPUs 90:10, MTP3, integrierte Vision |
| Large | `qwen-large` | 192.000 | IQ4_XS Pure, beide GPUs 86:14, MTP3, integrierte Vision |
| Ultra | `qwen-ultra` | 262.144 | maximaler Textkontext, IQ4_XS Pure auf RTX 5080 + RTX 3060 (80:20), ohne Vision-Projektor |
| Uncensored | `qwen-uncensored` | 80.000 | Abliterated Q4_K_M, 90:10, MTP2, integrierte Vision; nicht Default |
Manuell wird mit `llama-profile fast|medium|large|ultra|uncensored` gewechselt. Über HTTP stehen
`POST /fast`, `/medium`, `/large`, `/ultra` und `/uncensored` zur Verfügung. Ultra erreichte im
Referenzlauf etwa 68 Token/s; ein Prompt-Fülltest mit rund 220.000 Tokens war
erfolgreich. Medium ist das Start- und Standardprofil.
Uncensored reduziert modellseitige Verweigerungen, hebt aber keinerlei
Tool-Rechte auf. Destruktive Aktionen benötigen weiterhin Bestätigung und die
zentralen Secret-, Prompt-Injection- und Tool-Output-Filter bleiben aktiv.
## Clients
Clients verbinden sich mit:
```text
http://192.168.1.212:8081/v1
```
Dies ist die OpenAI-kompatible Router-API für Zettelrobbe, Hermes und andere
Clients im Heimnetz. `http://192.168.1.212:8080` ist ausschließlich
Open WebUI und darf nicht als API-Basisadresse eingetragen werden.
Als API-Key verwenden sie den Inhalt von `/etc/mike-ai/router-api-key` über
Bearer-Authentifizierung. Der Key gehört in den Secret-Store des Clients,
nicht in Chat, Repository oder URL. Eine Rotation erfolgt atomar durch
Ersetzen der Datei und Neustart des Routerdienstes.
Nur lokal auf Athena anzeigen und direkt in den Zielclient kopieren:
```bash
sudo cat /etc/mike-ai/router-api-key
```
Ein einfacher Verbindungstest ohne Ausgabe des Schlüssels:
```bash
ROUTER_API_KEY=$(sudo cat /etc/mike-ai/router-api-key)
curl -fsS http://192.168.1.212:8081/v1/models \
-H "Authorization: Bearer $ROUTER_API_KEY"
unset ROUTER_API_KEY
```
Sie sollen nicht direkt Port 8080 verwenden, weil sie sonst Profilumschaltung,
Vision, Bildgenerierung, STT und TTS umgehen.
## Status
- `GET /health`: Routerprozess lebt; bleibt bei geplantem Hotswap grün
- `GET /ready`: Router und Textmodell sind einsatzbereit
- `GET /status`: authentifizierter Detailstatus, Profil, Upstream, aktive Jobs
- `GET /v1/models`: virtuelle Modelle
- llama.cpp-Metriken: ausschließlich Docker-intern abfragen
- systemd-Journal: nur Metadaten und Fehler prüfen; keine Promptinhalte sammeln
## Upgrade-Regel
Niemals Build, Quantisierung und Profil gleichzeitig ändern. Immer genau eine
Variable ändern und anschließend denselben Benchmark ausführen.
Profilkontext und Alias werden zusätzlich in
`/etc/mike-ai/router-profiles.json` gepflegt. Änderungen an Override und
Registry gehören in denselben getesteten Commit; andernfalls verweigert die
Readiness bewusst die Freigabe.
## Fehler- und Recovery-Verhalten
- Ein Profilwechsel bricht ab, wenn laufende Chats nicht innerhalb des
Drain-Timeouts enden. Er beendet niemals absichtlich einen Chat.
- Nach einem Routerabsturz wird das letzte stabile Profil aus der atomaren
Zustandsdatei rekonstruiert.
- `/health = 200`, aber `/ready = 503` bedeutet: Router lebt, Modell ist noch
nicht bereit oder wird gerade gewechselt.
- `429` bedeutet, dass die Parallelitätsgrenze erreicht ist; der Client soll
mit Backoff erneut versuchen.
## Kapazitätsregeln
- Systempartition dauerhaft unter 85 Prozent halten.
- Mindestens 1 GiB Sicherheitsreserve für allgemeine GPU-Profile vorsehen;
experimentelle Max-GPU-Profile klar kennzeichnen.
- Nur ein Textmodell gleichzeitig laden.
- Benchmarks sind deaktivierte, manuell gestartete Jobs und keine Boot-Dienste.
## Backup
Gesichert werden:
- dieses Repository,
- lokale Modellmanifest-Datei mit Hashes, aber ohne Secrets,
- `/etc/mike-ai` verschlüsselt,
- systemd-Konfiguration,
- Benchmarkresultate.
Nicht gesichert werden müssen Build-Verzeichnisse, Venvs, Caches oder Modelle,
wenn Downloadquelle und Prüfsumme dokumentiert sind.
docs/PLATFORM_CONTEXT_MCP.md
-38
View File
@@ -1,38 +0,0 @@
# Athena Platform Context MCP
Der Context-MCP ist die kleine, ausschließlich lesende Auskunftsstelle für
Athena. Der verbindliche Einstieg ist die kurze Datei [`../ATHENA.md`](../ATHENA.md).
## Werkzeuge
| Werkzeug | Zweck | Grenze |
|---|---|---|
| `athena_get_overview` | liefert `ATHENA.md` | höchstens 14.000 Zeichen |
| `athena_get_current_state` | kompakter Host-Snapshot | keine Logs oder Secrets |
| `athena_get_external_services` | bekannte externe Dienste | keine freie Netzwerksuche |
| `athena_search_reference` | gezielte Quelltextsuche | höchstens 8 kurze Treffer |
| `athena_read_reference` | kleiner Dateiausschnitt | höchstens 160 Zeilen |
Ein fehlender Pfad ist ein normales Suchergebnis mit `retry: false`, kein
Serverfehler. Das verhindert Werkzeug- und Denkschleifen.
Der Container kann nichts verändern. Er hat keinen Docker-Socket, keine Shell,
keine Secrets und keinen Internetzugriff. Änderungen erledigt der Athena
Operator direkt im Git-Arbeitsbaum `/opt/mike-ai/stack`.
Der Host erzeugt einmal pro Minute einen begrenzten Snapshot. Er enthält nur
Host-/GPU-/Dateisystemdaten, Status und Image der `mike-ai-*`-Container, das
aktive Profil, den Git-Commit und den Recovery-Status. Prompts, Chats, Logs,
Container-Umgebungen und Secretwerte werden nicht erfasst.
## Verwendung
Für normale Athena-Arbeiten:
1. Überblick einmal lesen.
2. Zustand einmal prüfen.
3. Nur bei Bedarf gezielt suchen und kleine Ausschnitte lesen.
4. Danach mit dem Operator arbeiten; nicht alle Dokumente vorsorglich laden.
Historische Langdokumente unter `docs/` sind Nachschlagewerke. Sie werden nicht
automatisch in einen Modellkontext geladen.
docs/PLATFORM_OVERVIEW.md
-184
View File
@@ -1,184 +0,0 @@
# Athena / MikeAI – technische Detailübersicht
> Einstieg und verbindlicher Kurzstand: [`../ATHENA.md`](../ATHENA.md). Dieses
> Dokument enthält zusätzliche technische und historische Details und wird
> nicht vollständig in einen normalen Modellkontext geladen.
Stand: 23. August 2026. Diese Datei erklärt die Plattform in kurzer Form. Für
operative Änderungen gilt zusätzlich `QWEN_OPERATOR_CONTEXT.md`.
## Zweck
Athena ist ein selbst betriebener, datenschutzorientierter KI-Host. Er steht
physisch an einem entfernten Standort ohne KVM und wird ausschließlich remote
administriert. Open WebUI ist die einfache Benutzeroberfläche; Hermes Agent
ist der zweite Client für lange agentische Aufgaben. Ein eigener Profile
Router stellt eine OpenAI-kompatible API bereit und schaltet zwischen mehreren
reproduzierbaren llama.cpp-Profilen um. Fachwerkzeuge laufen als getrennte MCP-
Container; Zugangsdaten gelangen weder in llama.cpp noch in Modellprompts.
Der zuschaltbare `mike-ai-mcp-platform-context` stellt allen Textprofilen das
gleiche versionierte Plattformwissen zur Verfügung. Ein begrenzter
Host-Snapshot ersetzt einen Docker-Socket. Dokumentationsänderungen laufen nur
über Vorschau, ausdrückliche Freigabe und atomare Sicherung; Git und Recovery
bleiben getrennte, nachzuweisende Abschlussarbeiten. Details stehen in
`PLATFORM_CONTEXT_MCP.md`.
Das versionierte, secret-freie Diensteverzeichnis
`config/service-catalog.json` dokumentiert bereits vorhandene externe
Abhängigkeiten. Vor der Planung eines neuen Backends muss es gelesen und der
Bestand mit dem dort genannten Fachwerkzeug geprüft werden. Ein nicht
erreichbares Werkzeug bedeutet „nicht verifiziert“, niemals „nicht vorhanden“.
## Hardware
- Debian 13 `trixie`, Kernel 6.12
- AMD Ryzen 5 5600, 6 Kerne / 12 Threads
- 48 GiB DDR4-RAM
- RTX 5080 mit 16 GiB VRAM
- RTX 3060 mit 12 GiB VRAM
- System-SSD und getrennte `/data`-SSD, jeweils ungefähr 1 TB
- keine RX 470 mehr im System
GPU-Indizes auf dem Host sind nicht stabil genug für Konfigurationen. Wo eine
eindeutige Karte benötigt wird, werden GPU-UUIDs verwendet. Innerhalb eines
Containers kann `CUDA0` aufgrund von `NVIDIA_VISIBLE_DEVICES` eine andere Karte
bezeichnen als Index 0 von `nvidia-smi` auf dem Host.
## Hauptfluss
```text
Browser / OpenWebUI / Hermes Agent
|
| WireGuard, ausschließlich VPN
v
Open WebUI ---> Profile Router ---> Profile Controller ---> genau ein llama.cpp-Profil
| |
| +-- Vision direkt über Qwen + mmproj
| +-- FLUX-Hotswap für Bildgenerierung
| +-- Whisper für Speech-to-Text
| +-- TTS-Gateway -> XTTS-v2 -> Piper-Fallback
|
+-- internes MCP-Netz
+-- Athena Plattformwissen
+-- Web
+-- GitHub Repository read-only
+-- Home Assistant
+-- Sonarr/Radarr
+-- Navidrome
+-- Unraid
```
Hermes hängt parallel zu OpenWebUI direkt am Router und an denselben
MCP-Containern. Es betreibt kein zweites Qwen und verändert die Profilmatrix
nicht. Dashboard und Agent-API sind nur über WireGuard erreichbar; dauerhafte
Hermes-Daten liegen unter `/data/hermes` und sind Bestandteil des
verschlüsselten Recovery-Bundles.
Deemix läuft bereits als Container auf dem Unraid-HomeServer. Eine künftige
Deemix-MCP-Integration auf Athena verwendet dieses Backend über WireGuard und
erzeugt nicht ungefragt eine zweite Deemix-Instanz.
Automatische Unraid-Abfragen verwenden einen eigenen MUA-Read-only-Zugang, der
in Open WebUI ausschließlich Diagnosewerkzeuge sichtbar macht. Der vollständige
MUA-Verwaltungszugang bleibt davon getrennt und muss bewusst gewählt werden.
Beide Verbindungen sprechen denselben MCP-Endpunkt des MUA-Plugins auf dem
HomeServer an. Athena betreibt keinen zusätzlichen Unraid-GraphQL-MCP; die
GraphQL-API von Unraid darf deaktiviert bleiben.
Open WebUI und Router veröffentlichen keinen normalen Host-Port. Der
WireGuard-Gateway-Container stellt nur die vorgesehenen VPN-Endpunkte bereit.
Anwendungscontainer erreichen Heimnetz und Internet fail-closed über WireGuard;
ein Tunneldefekt darf nicht auf das Universitätsgateway zurückfallen. SSH auf
dem Debian-Host ist davon getrennt.
## Inferenzprofile
| Profil | Kontext | Modell/Verteilung | Zweck |
|---|---:|---|---|
| Fast | 76.800 | IQ4-MIX, Text auf RTX 5080 | schnell; Visionprojektor auf RTX 3060 |
| Medium | 160.000 | IQ4_XS Pure, 90:10 | Standardprofil; Vision; MTP3 |
| Large | 192.000 | IQ4_XS Pure, 86:14 | große Agentensitzungen; Vision |
| Ultra | 262.144 | IQ4_XS Pure, 80:20 | maximaler Textkontext, keine Vision |
| Uncensored | 80.000 | Abliterated Q4_K_M, 90:10 | weniger Verweigerungen; Rechte unverändert |
| Experimental | variabel | isoliert | Tests, niemals automatisch Produktion |
Es darf immer nur ein Textprofil aktiv sein. Medium ist der verbindliche
Standard. Ein „unkonditionierteres“ Modell hebt niemals Werkzeugrechte,
Bestätigungspflichten oder Netzwerkgrenzen auf.
## MCP-Prinzip
Ein Container entspricht einem Fachbereich und einer Vertrauensgrenze. Breite
Grundfähigkeiten werden jedoch nicht künstlich in Site-spezifische Werkzeuge
zerlegt: allgemeines Web ist immer verfügbar und der zentrale Athena Operator
besitzt ein begrenztes Terminal für neue Aufgaben. Fach-MCPs bleiben für kurze,
strukturierte API-Ergebnisse der bevorzugte Weg.
Der offizielle GitHub-MCP bietet nur drei Werkzeuge:
- Repository suchen
- Dateiinhalt lesen
- Code suchen
Rekursive Komplettbäume sind absichtlich ausgeschlossen, weil sie bei großen
Repositories den gesamten Modellkontext verdrängen können.
Andere GitHub-Werkzeuge sowie Schreibzugriffe sind serverseitig deaktiviert.
Für Entwicklung und Betrieb der KI-Plattform existiert ein zentraler Athena
Operator MCP. Eine unprivilegierte MCP-Fassade spricht ausschließlich über
einen Unix-Socket mit einem rootseitigen Executor. Dadurch kann Qwen MCPs,
Docker-Dienste, Modelle, Profile, OpenWebUI, Tests, Git und Recovery selbst
pflegen. Strukturierte Mutationen behalten Vorschau und Ticket; ein breites
Terminal deckt unvorhergesehene Arbeiten ab. Nur Strombefehle und Änderungen an
Athenas SSH, LAN, WireGuard, Firewall, Boot, Kernel, Mounts und Partitionen
bleiben zum Schutz der entfernten Erreichbarkeit blockiert.
## Verbindliche Quellen
1. aktuell mit einem zuständigen Werkzeug gemessener Laufzeitzustand
2. `CURRENT_REFERENCE.md` und `STANDARD_PROFILE_MATRIX.md`
3. Compose-, Installer- und Konfigurationsdateien im Repository
4. Architektur-, Sicherheits- und Betriebsdokumentation
5. frühere Chatangaben nur als Hinweis, niemals als aktueller Nachweis
Widersprechen Laufzeit und Dokumentation einander, wird nichts vorschnell
geändert. Die Abweichung wird benannt und zuerst geklärt.
## Unverhandelbare Sicherheitsregeln
- Keine Secrets, Tokens, privaten Schlüssel, Chats oder Promptinhalte auslesen
oder ausgeben, sofern das nicht ausdrücklich und eng begrenzt verlangt wurde.
- Kein Shutdown, Reboot, Netzwerk-, SSH-, Firewall-, WireGuard-, Kernel- oder
Bootloader-Eingriff ohne ausdrückliche Freigabe und belastbaren Rückweg.
- Keine Änderung direkt im Livecontainer als dauerhafte Lösung.
- Zuerst Bestand prüfen, dann versionierte Quelle ändern, testen, deployen,
verifizieren, dokumentieren und sichern.
- Bestehende fremde Änderungen und Dirty Worktrees erhalten.
- Niemals behaupten, etwas geprüft oder ausgeführt zu haben, wenn kein
zuständiges Werkzeug erfolgreich war.
## Wichtige Pfade
```text
/opt/mike-ai/stack einziger Git-Working-Tree und laufender Stack
/data/models produktive Modelle; für Inferenz read-only eingehängt
/etc/mike-ai root-only Secrets und Standortkonfiguration
/data persistente Daten- und Recovery-SSD
/var/lib/docker/volumes Docker-Volumes, darunter OpenWebUI-Daten
```
Kleine Quelländerungen erfolgen direkt über `athena_operator_change` mit
`patch_update`. Ein normaler MCP-Release kann mit `mcp_release` Tests, Deploy,
Client-Sync, Git-Publish und Recovery zusammenfassen.
Seit Operator 2.3 übernimmt `mcp_release.imports` bereits geprüfte UTF-8-Dateien
aus freigegebenen Staging-Verzeichnissen anhand ihrer SHA-256-Prüfsumme. Das
Modell muss lange vorbereitete MCP-Quellen weder erneut lesen noch im Chat
rekonstruieren. `hermes_sync: true` verteilt eine geänderte verwaltete
Hermes-Konfiguration ohne Containerneustart. Ein interner MCP benötigt keinen
neuen VPN-Port: Hermes und OpenWebUI erreichen ihn per Docker-DNS im Toolnetz.
Secrets unter `/etc/mike-ai` werden ausschließlich verschlüsselt gesichert und
gehören nie in Git, ein Wissensdokument oder einen Modellkontext.
docs/QWEN38-FINAL-PRE-MOVE-REPORT-2026-08-22.md
-156
View File
@@ -1,156 +0,0 @@
# Qwen3.8-Abschlusslauf vor dem Standortwechsel
Stand: 22. August 2026. Dieser Bericht dokumentiert den letzten isolierten
Abnahmelauf auf Athena vor dem Umzug des Hosts. Verwendet wurden ausschließlich
synthetische Prompts und Testbilder; keine Chats, privaten Prompts oder
Nutzerdaten wurden ausgewertet.
## Ergebnis in einem Satz
Die neue llama.cpp-Runtime wird übernommen, Medium erhält die nachweislich
schnellere MTP-Schwelle 0,05 und das neue, nicht standardmäßige Profil
`qwen-uncensored` wird mit 80K, Q4_K_M, 90:10 und MTP2 aufgenommen. Der
separate hochpräzise MTP-Draft wird verworfen, weil er die Ausgabe auf der
RTX-5080/RTX-3060-Kombination nahezu halbiert.
## Geprüfte Artefakte
| Artefakt | Quelle | SHA256 |
|---|---|---|
| Abliterated Q4_K_M | `Blackfrost-AI/Qwen3.8-27B-ABLITERATED-GGUF` | `5d53637a59cfcd3a4d8354e254ffd44943e5a693da2405a3e228c62962355509` |
| passender Abliterated-mmproj F16 | gleiche Quelle | `2284099ce864f1023d721e6ef5eaef32bb56abdbc1dc561c6d91300f12ef2e4b` |
| NVFP4-Trunk mit MTP-Metadaten | `LibertAIDAI/Qwen3.8-27B-NVFP4-MTP-GGUF` | `0fe21f4ce289f90108310f11065689c1496b56c7a8352b91ced16bd559691258` |
| separater hochpräziser MTP-Draft | gleiche Quelle | `e81b5dae9551b52190d06eae9db8a745057544893af32c828986ca053110a38c` |
Das Abliterated-Modell ist eine direkte Gewichtsablation und kein Merge mit
einem fremden Chat-Finetune. Tool Calling, Vision-Projektor und eingebettetes
MTP bleiben dadurch grundsätzlich verfügbar.
## llama.cpp A/B
| Runtime | Commit | Build | Medium 160K | Fast 76,8K | Start Medium |
|---|---|---:|---:|---:|---:|
| bisher | `4df29be4f4c3673f428170fda944a5b19f743bb8` | 10454 | 73,88 Tok/s | 85,75 Tok/s | 8,17 s |
| neu | `3f545beccee69d9975f466ec7e45fd9aacd8ba90` | 10587 | 73,86 Tok/s | 85,64 Tok/s | 6,08 s |
Die neun Antworten der beiden Medium-Läufe waren byte-identisch. Es gibt
keinen messbaren Inferenzgewinn, aber auch keine Regression. Übernommen wird
die neue Version wegen der zwischenzeitlichen Qwen-MTP-Korrekturen, des
expliziten `--mmproj-device`, der statischen CUDA-Workspace-Verbesserung und
weiterer Server-Härtungen.
## MTP-Abstimmung
| Medium-Konfiguration | Ergebnis |
|---|---:|
| MTP3, bisherige Schwelle 0,00 | 73,88 Tok/s |
| MTP2, Schwelle 0,10 | 73,80 Tok/s |
| **MTP3, Schwelle 0,05** | **77,26 Tok/s** |
| MTP4, Schwelle 0,10 | Startfehler, CUDA-OOM |
MTP3 mit `--spec-draft-p-min 0.05` bringt damit rund 4,6 Prozent mehr Ausgabe
ohne Änderung an Modell, Kontext, Quantisierung oder Antworten. Diese
Kombination wird für Medium übernommen. MTP4 ist für den verfügbaren VRAM zu
groß.
## Getrenntes Hauptmodell und separater MTP-Draft
| Aufbau | MTP | Ausgabe |
|---|---:|---:|
| NVFP4-Trunk mit eingebettet angefordertem Draft | 3 | Draft-Kontext konnte nicht initialisiert werden |
| NVFP4-Trunk 85:15, separater Draft vollständig auf RTX 3060 | 2 | 42,28 Tok/s |
| gleicher Aufbau | 3 | 35,95 Tok/s |
Die Trennung funktioniert technisch mit `--model-draft`, `--device-draft
CUDA1` und vollständigem Draft-Offload. Sie ist hier dennoch ungeeignet: Jede
Speculative-Runde wartet auf die wesentlich langsamere RTX 3060. Ein
hochpräziser Draft kauft keinen relevanten Qualitätsgewinn, halbiert aber fast
die Geschwindigkeit. Die beiden Testartefakte gehören daher nicht zur
Produktionsmatrix.
## Abliterated-/Uncensored-Tuning
| Kontext / Split | MTP | Vision | Ausgabe |
|---|---:|---|---:|
| 80K, 72:28 | 2 | ja | 44,74 Tok/s |
| 80K, 72:28 | 3 | ja | 40,44 Tok/s |
| 80K, 85:15 | 2 | ja | 50,24 Tok/s |
| 80K, 85:15 | 3 / p-min 0,05 | ja | 45,39 Tok/s |
| 80K, 90:10 | 3 / p-min 0,05 | ja | 47,13 Tok/s |
| **80K, 90:10** | **2 / p-min 0,10** | **ja** | **52,20 Tok/s** |
Der Gewinner lud in 5,15 Sekunden. Nach dem Laden waren rund 336 MiB auf der
RTX 5080 und 7,64 GiB auf der RTX 3060 frei. Der 60K-Fülltest verarbeitete
59.982 Prompt-Tokens in 94,16 Sekunden und fand den Sentinel korrekt wieder.
Der Vision-Test endete regulär, beschrieb das Testbild sachlich und erfand
keinen unlesbaren Text; die Vision-Ausgabe lief mit 49,79 Tok/s.
## Fachliche Bewertung
Die synthetische Suite prüfte Logik, evidenzgebundene Diagnose, Async-Code,
Kapazitätsplanung, Prompt-Injection, Home-Assistant-State gegen Konfiguration,
eine harmlose Admin-Diagnose, destruktive Bestätigung und die Grenze fehlender
Werkzeuge.
- Das offizielle Pure-Modell löste alle Kernaufgaben fachlich richtig. Zwei
Antworten erreichten wegen übermäßiger Ausführlichkeit das künstliche
Ausgabelimit, nicht das Kontextlimit.
- Das Abliterated-Modell löste die Logik-, Evidenz-, HA-, Injection- und
Tool-Ehrlichkeitsaufgaben im Endergebnis ebenfalls richtig.
- Bei der Migrationsaufgabe begann es einmal mit der falschen Behauptung
„möglich“, korrigierte sich anschließend aber vollständig und bewies die
Unmöglichkeit. Das ist fachlich am Ende korrekt, aber weniger sauber.
- Der Async-Vorschlag ist brauchbar, besitzt jedoch einen subtilen Randfall,
wenn mehrere Tasks gleichzeitig fertig werden: bereits fertige Exceptions
sollten vor dem frühen Return vollständig konsumiert werden.
- Beim destruktiven Auftrag blieb die Ausführung korrekt aus und der sichere
Alternativweg wurde genannt. Die Formulierung zur verlangten
Log-Unterdrückung war stellenweise weniger hart als beim Pure-Modell. Daher
bleibt dieses Profil bewusst kein Admin-Default und behält sämtliche
externen Tool-/Bestätigungs- und Secret-Grenzen.
Die Gewichtsablation macht das Modell also weniger verweigerungsfreudig, aber
nicht intelligenter als Pure. Für komplexe Administratoraufgaben bleibt Medium
die vertrauenswürdigere Standardwahl. Uncensored ist eine gezielt auswählbare
Alternative für zulässige Aufgaben, bei denen das Standardmodell unnötig
blockiert.
## Übernommene Produktionswerte
| Profil | Änderung |
|---|---|
| Medium | neue llama.cpp-Runtime und MTP3 mit p-min 0,05 |
| Uncensored | neu: Abliterated Q4_K_M, 80K, 90:10, MTP2, eigener mmproj auf RTX 3060 |
| Fast/Large/Ultra | Modellmatrix unverändert; neue gemeinsame Runtime |
| Default | bleibt Medium 160K |
## Produktionsabnahme des Routers
Beim ersten realen Profilwechsel zeigte die neue Runtime eine kleine, aber
wichtige Kompatibilitätsänderung: Mit MTP meldet llama.cpp für ein angefordertes
80K-Fenster intern 80.128 Tokens. Der Router verlangte zuvor exakte Gleichheit
und wartete deshalb trotz gesundem Modell bis zum Timeout. Die Prüfung
akzeptiert nun ausschließlich einen kleinen technischen Aufschlag von maximal
1.024 Tokens; Modellalias und Profilgrenzen werden weiterhin streng geprüft.
Nach der Korrektur wurden folgende End-to-End-Prüfungen bestanden:
- Router-Modellliste enthält Fast, Medium, Large, Ultra und Uncensored.
- Uncensored wird mit 80K, 90:10, MTP2 und eigenem Vision-Projektor gesund.
- Wechsel Uncensored → Medium über die authentifizierte Router-API: 5,75 s.
- Synthetischer Chat über OpenWebUI-Netz → Router → Medium: korrekte Antwort
`READY` in 0,58 s.
- Medium ist anschließend wieder aktives und gesundes Standardprofil.
- 27 lokale Unit-Tests sowie Python-Kompilierung und Compose-Validierung
bestanden.
Die verworfene Split-NVFP4-/separate-Draft-Kopie wurde nach der Abnahme vom
Host entfernt und gab rund 21 GB frei. Die vorherige llama.cpp-Runtime bleibt
bis nach dem physischen Umzug als lokales Rollback-Image erhalten.
## Rohdaten
Die vollständigen synthetischen Antworten, Serverlogs, Timings und GPU-Snapshots
liegen unter `benchmarks/qwen38-final-pre-move-20260822/`. Die drei Unterordner
bilden den breiten Runtime-/MTP-Lauf, das Split-Tuning und die finale
Uncensored-Abnahme ab.
docs/QWEN38_AGENTIC_BENCHMARK_2026-08-24.md
-90
View File
@@ -1,90 +0,0 @@
# Qwen3.8-27B – agentischer Werkzeugtest vom 24. August 2026
## Ergebnis in einem Satz
Qwen3.8-27B ist auf Athena für längere agentische Aufgaben brauchbar, wenn die
Werkzeugschicht ihm gebündelte Fachoperationen, erhaltenes Reasoning und eine
garantierte Schlussrunde anbietet. Die früheren Ausfälle waren überwiegend
Orchestrierungs- und MCP-Probleme, nicht ein grundsätzliches Unvermögen des
Modells.
## Warum die Community-Erfahrungen besser wirkten
Community-Demos verwenden meist einen spezialisierten Agent-Harness, große
Kontexte, erhaltenes Reasoning und kompakte Werkzeuge. Athena kombinierte zuvor
76K Kontext, standardmäßig abgeschaltetes Thinking, sechs Einzelaufrufe,
teilweise sehr kleinteilige MCP-Operationen und OpenWebUIs hartes Ende ohne
Syntheserunde. Zusätzlich existieren aktuelle llama.cpp-Randfälle bei
Qwen3.8-Systemnachrichten, verschachtelten Werkzeugschemata und gestreamten
Parallelaufrufen. Die Differenz war daher kein fairer Modellvergleich.
## Produktive Änderungen
- `--reasoning-preserve` in allen Qwen-Profilen.
- Automatische Auswahl von bis zu drei Fach-MCPs.
- Automatisch mittleres, auf 3.072 Token begrenztes Reasoning nur bei echten
Mehrdomänen-Aufgaben; explizite Benutzereinstellungen werden nicht ersetzt.
- Zwölf tatsächliche Aufrufe, höchstens vier pro Werkzeug, keine identische
Signatur zweimal; 16 interne Runden lassen Raum für die Schlussantwort.
- Genau ein zusätzlicher werkzeugloser Syntheseversuch, falls Qwen nach Ende
der Recherche trotzdem noch einen Funktionsaufruf formuliert.
- Home Assistant `find_commented_blocks`: vollständige auskommentierte
Automationseinträge einschließlich ID, Alias und Zeilen in einem Aufruf.
- MUA r017: gebündelte CA-Suche mit bis zu fünf Namensvarianten.
- MUA r018: fokussierte Loganalyse mit mehreren `focus_terms` in einem Aufruf.
- Evidenzplan im Systemprompt: zuerst ein breiter Aufruf je Domäne, danach nur
gezielte Lücken schließen, Pflichtbedingungen früh prüfen und bei deren
Scheitern sofort den Kandidaten wechseln.
## Browser-Benchmarks
| Test | Vorher | Nachher | Bewertung |
|---|---:|---:|---|
| Auskommentierte HA-Automationen inventarisieren | 9 Aufrufe, 90,9 s | 1 Aufruf, 26,8 s | IDs, Aliase und Zeilen korrekt; sehr gut |
| Deemix: GitHub + laufender Unraid-Container + MCP-Entwurf | zuvor 37 GitHub-Aufrufe und Abbruch | 7 Aufrufe, sichtbare Antwort | klare Verbesserung; einzelne Betriebsannahmen noch zu optimistisch |
| Web + GitHub + Unraid: CA-Negativprüfung und Template-Entwurf | Kandidat zu spät verworfen, Budgetende | 11 Aufrufe, vollständiger Entwurf | Schlussantwort vorhanden; XML und Architektur müssen weiterhin fachlich geprüft werden |
| Drei Domänen: HA-YAML + Unraid-Logs + GitHub-Quelle | vorher kein finaler Text am Budgetende | 12 Aufrufe, vollständige Evidenzmatrix | Finalizer v5 bestanden; Quellenverwechslung wurde transparent als Unsicherheit markiert |
| Fokussierte Home-Assistant-Logprüfung | mehrere Shell-/grep-Aufrufe | 1 Inventar + 1 fokussierte Loganalyse, 44,7 s | MUA r018 korrekt gewählt; klare Beleggrenzen |
## Qualitätsbefund
### Stark
- wählt nach der Anpassung die drei korrekten Fachdomänen automatisch;
- beginnt parallel/breit und liefert belastbare Livewerte;
- kann aus Werkzeugresultaten strukturierte Evidenzmatrizen und sichere Pläne
bauen;
- verschweigt verbleibende Unsicherheit überwiegend nicht;
- die HA-Spezialoperation reduziert Laufzeit und Kontextverbrauch drastisch.
### Noch nicht auf Frontier-Agent-Niveau
- bei ähnlichen GitHub-Repositories kann Qwen den falschen Treffer vertiefen,
statt zuerst den exakten installierten Upstream zu bestimmen;
- bei komplexen Containerstacks erzeugt es gelegentlich formal plausible,
aber fachlich fragwürdige Unraid-XMLs;
- ohne gebündelte Logoperation fällt es auf mehrere Shell-/grep-Aufrufe zurück;
- zwölf Werkzeugaufrufe sind kein Qualitätsbeweis: Die Auswahl und Form der
Werkzeuge sind wichtiger als eine möglichst große Zahl.
## Empfehlung
Fast bleibt für normale Aufgaben geeignet. Für Änderungen, längere Recherche
oder mehrere Systeme gleichzeitig soll das automatische Mehrdomänen-Reasoning
greifen; bei besonders kritischer Arbeit kann Thinking manuell auf Hoch gesetzt
werden. Ergebnisse, die Installationen, Sicherheit, Geld oder Datenänderungen
betreffen, benötigen weiterhin Vorschau, Belegprüfung und Freigabe. Weitere
Verbesserungen sollten bevorzugt gebündelte Fachoperationen ergänzen und nicht
das globale Aufruflimit erhöhen.
## Versionierte Quellen
- Qwen3.8-27B Modellkarte: <https://huggingface.co/Qwen/Qwen3.8-27B>
- OpenWebUI native tool calling:
<https://github.com/open-webui/docs/blob/main/docs/features/extensibility/plugin/tools/index.mdx>
- llama.cpp Systemnachrichten-Randfall:
<https://github.com/ggml-org/llama.cpp/issues/27367>
- llama.cpp verschachtelte Schemas:
<https://github.com/ggml-org/llama.cpp/issues/21771>
- llama.cpp Streaming/Parallel-Toolcalls:
<https://github.com/ggml-org/llama.cpp/issues/18591>
docs/QWEN_OPERATOR_CONTEXT.md
-16
View File
@@ -1,16 +0,0 @@
# Qwen Operator Context
Diese frühere Langdokumentation wurde durch die kurze, verbindliche
[`../ATHENA.md`](../ATHENA.md) und den Hermes-Skill
[`../platform/hermes/skills/athena-operator/SKILL.md`](../platform/hermes/skills/athena-operator/SKILL.md)
ersetzt.
Für einen neuen Chat genügt:
> Arbeite dich mit dem Athena-Plattformwissen ein und erledige den Auftrag nach
> dem Athena-Operator-Skill.
Der Platform Context MCP liefert den Überblick sowie kleine Such- und
Leseausschnitte. Der Athena Operator führt Änderungen direkt im einzigen
Git-Arbeitsbaum `/opt/mike-ai/stack` aus. Alte mehrstufige Doku-, Ticket- und
Repo-Sync-Verfahren gelten nicht mehr.
docs/RECOVERY.md
+61
View File
@@ -0,0 +1,61 @@
# Backup und Wiederherstellung
## Was automatisch gesichert wird
Der Container `mike-ai-backup` erstellt alle fünf Stunden ein komprimiertes
Archiv unter `/data/docker-backups` und behält 14 Tage. Während der kurzen
Sicherung wird nur OpenWebUI angehalten, damit seine SQLite-Datenbank konsistent
ist. Netzwerk, WireGuard, Router, Hermes und Qwen bleiben erreichbar.
Enthalten sind:
- `/etc/mike-ai` mit lokalen Konfigurationen und Secrets
- OpenWebUI-Daten
- Router-Zustand und Router-Bildablage
- Piper-Daten
- TinySearch-Modellcache
- ein Quellbaum-Snapshot als zusätzliche Bequemlichkeit
Nicht kopiert werden `/data/models`, `/data/hermes` und
`/data/hermes-webui`: Sie liegen bereits dauerhaft auf der Daten-SSD und
überleben den Austausch der Debian-Systemplatte. Docker-Images werden aus dem
Compose-Stack reproduziert und gehören nicht ins Backup.
## Manuelles Backup
```bash
docker exec mike-ai-backup backup
```
Die Datei `/data/docker-backups/athena-latest.tar.gz` zeigt danach auf das
neueste erfolgreiche Archiv.
## Neuaufbau
1. Debian installieren und `/data` wieder unter demselben Pfad einhängen.
2. Repository klonen.
3. Installation einmal ausführen:
```bash
sudo ./install.sh --config config/install.env
```
4. Zustand mit einem Befehl wiederherstellen:
```bash
sudo ./restore.sh /data/docker-backups/athena-latest.tar.gz
```
Das Restore stoppt ausschließlich Container, deren Volumes zurückgeschrieben
werden. SSH, LAN und WireGuard werden nicht verändert.
## Kontrolle
```bash
docker compose --env-file /etc/mike-ai/stack.env ps
test -s /data/docker-backups/athena-latest.tar.gz
```
Danach einen OpenWebUI-Login, einen Router-Request und je einen read-only
MCP-Aufruf testen. Alte Recovery-Koffer sind für Neuinstallationen nicht mehr
erforderlich; Git plus dieses Datenbackup bilden die Wiederherstellung.
docs/RECOVERY_REQUIREMENTS.md
-226
View File
@@ -1,226 +0,0 @@
# Noch benötigte Wiederherstellungsartefakte
Diese Liste definiert, was vor einer Löschung oder grundlegenden Änderung des
alten Hosts noch gesichert beziehungsweise präzisiert werden muss.
Statuswerte:
- **gesichert**: vollständig im Git oder anderweitig reproduzierbar
- **offen**: muss vor dem Neuaufbau erledigt werden
- **lokal geheim**: darf nicht unverschlüsselt ins Git
## 1. Modelle und Prüfsummen – offen, höchste Priorität
Für jedes tatsächlich benötigte Modell werden erfasst:
- exakte Downloadquelle und Repository-ID
- Revision oder Commit
- Dateiname und Splitreihenfolge
- Dateigröße
- SHA256 jeder Datei
- Lizenz
- Zielpfad
- zugehöriger mmproj/MTP-Tensor
- getestete Runtime und Profilzuordnung
Das Ergebnis wird als `platform/models/manifest.local.yaml` erzeugt. Die Datei
enthält keine Geheimnisse, kann aber wegen möglicher privater Quellen zunächst
lokal bleiben. Eine bereinigte Fassung gehört anschließend ins Git.
Pflichtrollen:
- Qwen Fast IQ4-MIX
- Qwen Medium/Large/Ultra IQ4_XS Pure
- Qwen Uncensored Abliterated Q4_K_M samt passendem F16-Projektor
- BF16 Vision-Projektor
- Whisper large-v3-turbo
- FLUX.2 klein
- XTTS-v2, per Digest gepinntes CUDA-12.1-Image und CPML-Akzeptanz
- XTTS-Stimme `Annmarie Nele`, RTX-3060-UUID und persistenter Modellcache
- internes TTS-Gateway mit Queue, Sprachsegmentierung und Piper-Fallback
- Piper `piper-tts` 1.6.0 und Stimme `de_DE-thorsten-high` als CPU-Fallback
## 2. Externe Komponenten und Commits – teilweise gesichert
Im Repository gesichert sind inzwischen:
- getrennte MCP-Container und internes Netz
- Web-MCP-Fassade sowie gepinnte TinySearch-/SearXNG-Images
- ARR-MCP 1.0.1 und der aktuell eingesetzte kompakte Sonarr-Patch
- offizieller GitHub-MCP 1.10.1 hinter `mcp-proxy` 0.12.0; GitHub- und
Python-Basisimage per Digest gepinnt
- GitHub-Transport stateless und mit OpenWebUIs Python-MCP-Client geprüft
- Home-Assistant-Relay ohne eingebettetes Token
- Startlogik und Health-Checks
Noch extern zu beschaffen und exakt festzuhalten sind:
- Home-Assistant-MCP
- MUA-Plugin auf dem Unraid-HomeServer sowie die root-only gesicherte
`/etc/mike-ai/mua-mcp.env`
- LLama-GUI, falls sie erhalten bleibt
Jede noch externe Komponente bekommt zusätzlich:
- Installationsbefehl
- Systembenutzer
- systemd-/Docker-Datei
- Health-Check
- benötigte Environment-Namen ohne Werte
- Liste read-only und schreibender Werkzeuge
## 3. Basissystem-Bootstrap – umgesetzt, Praxistest offen
`install.sh` erstellt inzwischen:
- Paketquellen und benötigte Debian-Pakete
- NVIDIA-Treiber und exakte Version
- CUDA Toolkit und Buildabhängigkeiten
- Docker und Compose
- die benötigten Container-Runtimes und Dienstbenutzer in Images
- Verzeichnisse, Eigentümer und Dateirechte
- Firewallregeln
- Journalgrößenlimit
- automatische Sicherheitsupdates nach bewusstem Freigabemodell
Das Skript darf weder formatieren noch Modelle löschen. Destruktive
Speicheroperationen bleiben ein separater, ausdrücklich bestätigter Schritt.
## 4. Secret-Verfahren – lokal geheim
Benötigt wird ein festes Verfahren für:
- Home-Assistant-Token
- Sonarr-/Radarr-API-Schlüssel
- Unraid-Zugang
- Navidrome-Benutzer und Last.fm API-Key
- optionale GitHub-, Hugging-Face- und Brave-Schlüssel
- SSH-Hostschlüssel und bekannte Hosts
Umgesetzt ist ein age-verschlüsseltes Bundle über
`platform/recovery/create-recovery-bundle.sh` und der zugehörige
Bare-Metal-Restore. Noch standortspezifisch festzulegen ist ausschließlich das
externe Zielverzeichnis auf Unraid.
Verbindlich bleiben:
- verschlüsseltes Backupformat, beispielsweise age oder ein Passwortmanager
- Besitzer und Rechte je Environment-Datei
- Rotation und Widerruf
- Restore ohne Ausgabe der Werte in Terminal- oder Modellkontext
- Funktionstest mit ausschließlich Statuscode, niemals Tokenanzeige
## 5. Netzwerk und DNS – Vorlage umgesetzt, Standortwerte offen
Dokumentiert werden müssen:
- endgültiger Hostname
- statische Adresse oder DHCP-Reservierung
- DNS-Name
- erlaubte Client-Netze
- Firewallmatrix pro Port
- TLS/Reverse Proxy, sofern verwendet
- Verhalten bei Neustart und fehlendem Netzwerk
Zielmatrix:
| Port | Zugriff |
|---:|---|
| 22 | nur Administration |
| 8080 | ausschließlich WireGuard-Gateway (Open WebUI) |
| 8081 | ausschließlich WireGuard-Gateway (Router) |
| 8084 | localhost |
| 8085 | localhost |
| 8000 | localhost |
| 5240 | optional nur Administration |
Open WebUI und Router selbst besitzen keine Host-Portfreigaben. Zusätzlich zum
Repository muss die verschlüsselt gesicherte Fritzbox-Clientdatei als
`/etc/mike-ai/wireguard/fritz-athena.conf` (0600) wiederhergestellt werden.
## 6. Speicherlayout – offen
Vor dem Neuaufbau festlegen:
- System, Modelle, Caches und Ergebnisse auf getrennten Mounts
- Dateisystem des Modelllaufwerks
- Mindestreserve und Warnschwellen
- Docker-Datenpfad
- Hugging-Face- und Python-Cachepfade
- Backupziel
- Aufbewahrungsregeln für Bilder, Audio und Logs
Empfehlung: System unter 85 Prozent, Modelllaufwerk unter 90 Prozent halten.
## 7. Runtime-Locks – teilweise gesichert
Bereits gesichert:
- llama.cpp-Commit
- zentrale Python-Versionen für FLUX und Piper
- TinySearch-/SearXNG-Image-Digests
Noch offen:
- vollständiges `pip freeze` je produktivem Venv
- CUDA-kompatible Wheel-Quelle
- FLUX-Revision
- Piper-Paketversion und exakter Stimmenname
- Whisper-Commit und Buildoptionen
- Docker-Engine-/Compose-Version
## 8. Betriebsdaten und Aufbewahrung – offen
Festlegen, welche Daten persistent sein sollen:
- generierte Bilder: standardmäßig zeitlich begrenzt
- Audiodateien: standardmäßig nicht dauerhaft
- Vision-Cache: flüchtig
- Chatverläufe: nicht Bestandteil dieser Plattform
- Benchmarkresultate: eigenes Repository
- Logs: ohne Prompt- und Tool-Antwortinhalte
## 9. Ende-zu-Ende-Installer – weitgehend implementiert, Praxistest offen
Der Ablauf ist jetzt in `install.sh` zusammengeführt:
```text
bootstrap-host
install-runtime
verify-model-manifest
install-platform
restore-secrets
enable-selected-mcp-profiles
run-acceptance-tests
```
`platform/mcp/install-tools.sh` installiert den Webbereich automatisch und
aktiviert HA, ARR, Navidrome und Unraid nur bei vorhandenen
Secret-/Programmdateien.
`platform/migration/restore-reference-backup.sh` importiert eine bestehende
OpenWebUI-Datenbank und ausschließlich die freigegebenen Tool-Secrets, ohne
experimentelle Altcontainer zurückzubringen. Der Leerhost-Probelauf wird auf
Athena praktisch protokolliert und seine Korrekturen fließen direkt in den
Installer zurück.
Ein Container-Backup gilt nur dann als vollständig, wenn nach `docker save`
nicht bloß das Archiv und seine Prüfsumme existieren: Ein isolierter
Probeimport muss außerdem jede erwartete Image-ID beziehungsweise den
unveränderlichen Registry-Digest und die OCI-Build-Revision bestätigen. Die
OpenWebUI-Datenbank wird immer zusammen mit genau diesem geprüften Image
gesichert und wiederhergestellt.
Jeder Schritt muss wiederholbar, einzeln prüfbar und bei Fehlern abbrechbar
sein. Ein fehlgeschlagener Schritt darf keinen halb aktivierten Dienst
hinterlassen.
## 10. Dokumentations-Abnahmekriterium
Der alte Host darf erst verworfen werden, wenn eine fachkundige Person mit:
1. diesem Repository,
2. den dokumentierten Modellquellen,
3. dem verschlüsselten Secret-Backup
einen leeren Host ohne Wissen aus früheren Chats vollständig in Betrieb nehmen
kann.
docs/REMOTE_SITE_CHECKLIST.md
-83
View File
@@ -1,83 +0,0 @@
# Checkliste für einen unbeaufsichtigten Standort
Athena wird ohne lokales KVM betrieben. Vor dem Transport müssen Betriebssystem,
UEFI und Heimtunnel gemeinsam geprüft werden. Keine einzelne Maßnahme ersetzt die
anderen.
## UEFI des ASUS PRIME B550-PLUS
Im UEFI mit `F7` in den Advanced Mode wechseln und unter
`Advanced > APM Configuration` setzen:
- `Restore AC Power Loss`: **Power On**
- `Power On By PCI-E`: **Enabled**
- `ErP Ready`: **Disabled** (sonst kann Wake-on-LAN abgeschaltet werden)
Empfohlen ist zusätzlich ein kontrollierbarer Zwischenstecker. Nach einem
erzwungenen Aus- und Wiedereinschalten der Netzspannung startet Athena durch
`Restore AC Power Loss = Power On` selbständig. Der Zwischenstecker darf nicht
für normale Neustarts verwendet werden.
## Debian
Der Installer aktiviert standardmäßig den vorhandenen SP5100-Hardware-Watchdog
mit 60 Sekunden und konfiguriert Wake-on-LAN für das in
`WAKE_ON_LAN_INTERFACE` genannte Interface. Das primäre Interface wird sowohl
beim Boot als auch bei einem später erkannten Kabel aktiviert. SSH und Docker
müssen aktiviert sein.
Die physische Netzwerkkarte wird über ihre permanente MAC-Adresse erkannt und
durch `/etc/systemd/network/10-athena-lan.link` fest `lan0` genannt. Damit
ändert sich der produktive Interface-Name nicht, wenn Grafikkarten oder andere
PCIe-Geräte ergänzt oder entfernt werden. Nach der erstmaligen Einrichtung
beendet sich der Installer mit Exit-Code 21; nach dem erforderlichen Neustart
wird derselbe Installationsbefehl erneut ausgeführt.
Vor dem Transport prüfen:
```bash
systemctl is-enabled ssh docker mike-ai-container-vpn-guard
systemctl is-active ssh docker mike-ai-container-vpn-guard
ip link show lan0
ethtool lan0 | grep Wake-on
systemctl show -p RuntimeWatchdogUSec
docker inspect -f '{{.State.Health.Status}}' mike-ai-wireguard-gateway
docker exec mike-ai-wireguard-gateway wg show wg0 latest-handshakes
```
Erwartet werden `enabled`, `active`, `Wake-on: g`, ein Watchdog-Wert von einer
Minute sowie ein aktueller WireGuard-Handshake.
## Netzwerk und VPN
- Der physische Anschluss bezieht seine Adresse per DHCP; im Standortnetz muss
dafür eine Freigabe bzw. Registrierung existieren.
- SSH bleibt auf der Standort-Schnittstelle erreichbar, akzeptiert aber nur
Public-Key-Anmeldungen. Vor dem Transport muss der Schlüsselzugriff getestet
werden.
- Zusätzlich stellt das WireGuard-Gateway unter seiner VPN-Adresse Port 22 als
key-only SSH-Notweg zum Host bereit. Der Listener ist explizit an `wg0`
gebunden und wird nicht auf dem Standort-Interface veröffentlicht.
- Der WireGuard-Tunnel muss **vor dem Transport** erfolgreich aufgebaut und von
zuhause erreichbar getestet sein.
- Für WireGuard braucht Athena keine eingehende Portfreigabe am Standort: Der
Host baut den Tunnel mit `PersistentKeepalive = 25` nach Hause auf.
- Wake-on-LAN funktioniert über Stadtgrenzen nur, wenn ein Gerät im Standortnetz
das Magic Packet senden darf. Der robuste Notweg ist deshalb der steuerbare
Zwischenstecker plus `Restore AC Power Loss = Power On`.
- SSH über das Standortnetz erst dann einschränken, wenn der VPN-Notweg nach einem
echten Neustart nachweislich funktioniert.
## Pflichtproben vor Abfahrt
1. Normaler Neustart: VPN, SSH, Docker, Open WebUI und Medium-Profil kommen zurück.
2. Rechner sauber herunterfahren und per Wake-on-LAN einschalten.
3. Netzspannung bei laufendem Rechner trennen, 30 Sekunden warten, wieder
einschalten: Athena bootet automatisch vollständig hoch.
4. `mike-ai-wireguard-gateway` stoppen: Container-Egress muss scheitern;
Gateway wieder starten und aktuellen Handshake prüfen.
5. Von zuhause aus ausschließlich über die spätere VPN-Adresse zugreifen.
Dabei sowohl Open WebUI als auch `ssh root@<WIREGUARD-IP>` prüfen.
Ohne erfolgreich getesteten WireGuard-Tunnel und die UEFI-Stromoptionen gilt der
Host nicht als bereit für einen unbeaufsichtigten Standort.
docs/ROUTER_V2_MIGRATION.md
-62
View File
@@ -1,62 +0,0 @@
# Router V2 – Migration und Kompatibilität
> Historischer Stand: Die damalige Bezeichnung `long` wurde am 22. August
> 2026 durch `large` ersetzt und um `ultra` ergänzt. Für den aktuellen Betrieb
> gilt ausschließlich `STANDARD_PROFILE_MATRIX.md`.
## Ergebnis
V2 behält die OpenAI-kompatible Basis-URL und die virtuellen Modelle
`qwen-fast`, `qwen-medium` und `qwen-long`. Bestehende Chat-, Tool-, Audio-,
Vision- und Bildpfade bleiben erhalten. Die Änderungen betreffen absichtlich
die Stellen, an denen der alte Router unsicher oder nicht deterministisch war.
## Bewusste Änderungen
| Alt | V2 |
|---|---|
| alle LAN-Clients ohne Authentifizierung | API-Key für alle fachlichen Endpunkte |
| `GET /fast` schaltet ein Modell | nur noch `POST /fast` (analog medium/long) |
| `/health` hängt am Modellzustand | `/health` = Prozess, `/ready` = Textmodell |
| Profil durch Textvergleich erkannt | Kontext + Alias aus Profilregister geprüft |
| Profilwechsel und Request konnten sich überholen | atomare Modell-Lease |
| Drain-Timeout beendete trotzdem das Modell | Wechsel wird sicher abgebrochen |
| Workerzustand nur im RAM | atomare Zustandsdatei und Startup-Recovery |
| beliebige Bild-URL | Data-URL, Größenlimit; Remote standardmäßig aus |
| unbegrenzte Parallelität und Bildablage | Request- und Retention-Limits |
| Auth-Header potenziell am Upstream | Router-Credentials werden entfernt |
## Client-Migration
1. Router-Key aus `/etc/mike-ai/router-api-key` ohne Anzeige in einen lokalen
Secret-Store des Clients übernehmen.
2. Basis-URL unverändert auf `http://HOST:8081/v1` lassen.
3. Den Key als OpenAI-API-Key/Bearer-Token konfigurieren.
4. `GET /v1/models` testen und anschließend einen kurzen Chat über
`qwen-fast` senden.
5. Automationen, die Profile per GET schalten, auf POST umstellen.
6. Überwachung auf `/health` (Liveness) und `/ready` (Readiness) aufteilen.
## Sicheres Rollout
V2 wird nicht blind über einen laufenden Router kopiert:
1. Repository-Commit und aktuelle produktive Konfiguration sichern.
2. Profilregister gegen alle drei systemd-Overrides prüfen.
3. API-Key erzeugen und Clients vorbereiten.
4. Router installieren und zuerst lokal mit Key prüfen.
5. Fast, Medium und Long jeweils einmal schalten und Alias/Kontext prüfen.
6. Streaming und einen Tool Call testen.
7. Erst danach normale Clients auf V2 freigeben.
Ein Rollback stellt Routerdateien und Unit aus dem Installationsbackup wieder
her. Der neu erzeugte API-Key und die Zustandsdatei enthalten keine
Modelldateien oder Chatdaten.
## Verbleibender Architekturpunkt
Der Routerprozess läuft derzeit als root, weil er den systemweiten llama.cpp-
Dienst und temporäre GPU-Worker steuert. Die Unit ist stark gehärtet, dennoch
ist das nicht das langfristige Ideal. V3 soll HTTP/API und privilegierte
Orchestrierung trennen: unprivilegierter Proxy plus kleiner Root-Helper mit
festen, nicht frei parametrisierbaren Aktionen.
docs/SECURITY.md
-78
View File
@@ -1,78 +0,0 @@
# Sicherheitsmodell
## Netzgrenze
- Open WebUI und Router veröffentlichen keinerlei Host-Ports.
- Ein dedizierter WireGuard-Container stellt OpenWebUI, Router und die
Werkzeugdienste direkt auf seiner VPN-Adresse bereit. Die verbindliche
Portmatrix steht in [VPN_SERVICE_PORTS.md](VPN_SERVICE_PORTS.md).
- Die egressfähigen Docker-Netze verwenden eigene Routingtabellen.
- Heimnetz- und optionaler Internetverkehr laufen über WireGuard.
- Die Tabellen zeigen ausschließlich zum Gateway-Container und besitzen keine
Route über das Standortgateway. Das ist der Fail-Closed-Mechanismus.
- Der Host ist kein Router zwischen Universitäts- und Heimnetz.
Da keine KI-Ports publiziert werden, kann Docker die Host-Firewall an dieser
Stelle nicht umgehen. SSH bleibt davon getrennt und schlüsselbasiert auf der
physischen Schnittstelle erreichbar.
## Containergrenzen
- llama.cpp: read-only, keine Capabilities, Modelle read-only, keine Ports.
- Router: unprivilegierter Benutzer, kein Docker-Socket, feste API-Oberfläche.
- Profile Controller: einzige Socket-Ausnahme; feste Profile und nur
List/Start/Stop, keine frei wählbaren Images, Befehle oder Mounts.
- Open WebUI: einziges persistentes Chat-Volume.
- MCP-Fachcontainer: intern verbunden und über feste WireGuard-Ports direkt
für OpenWebUI, Pi, Hermes und andere Heim-VPN-Clients erreichbar.
- TinySearch/SearXNG: intern, Suchanfragen ohne Chatverlauf.
llama.cpp bekommt weder MCP-Konfiguration noch HA-, ARR- oder Unraid-Secrets.
Open WebUI kann weiterhin die internen MCP-Namen verwenden. Andere Clients
nutzen ohne zusätzliches Gateway die festen MCP-Ports der WireGuard-Adresse.
Authentisierung zu den Zielsystemen findet im jeweiligen Fachcontainer statt.
Ein Docker-Socket bleibt grundsätzlich privilegiert. Der Controller reduziert
die erreichbare Funktion stark, ersetzt aber keine zusätzliche Socket-Proxy-
Sandbox. Er ist klein, testbar und nicht von Clients direkt erreichbar.
## Secrets und private Daten
- Keine Secrets in Git, Prompts, MCP-Schemas, Logs oder Screenshots.
- Installer-Konfiguration und `/etc/mike-ai/*` haben restriktive Rechte.
- Router-, Controller- und WebUI-Schlüssel sind getrennt und zufällig.
- Das Modell bekommt keine Schlüsselwerte zurück; spätere Integrationen nutzen
lokale Broker/Environment-Dateien.
- Open-WebUI-Volume kann Chats enthalten und wird nur verschlüsselt gesichert.
## Werkzeugprofile
| Modus | Erlaubte Werkzeuge |
|---|---|
| Standard | lokale Websuche, harmlose Hilfsfunktionen |
| Home Assistant | eigener begrenzter HA-MCP |
| ARR | Sonarr/Radarr, zuerst read-only |
| Unraid Diagnose | Status und eng begrenzte Logs |
| Administration | Vorschau, Approval-Ticket, Verifikation |
Für die Athena-Plattform existiert genau ein Operator-MCP. Seine unprivilegierte
Fassade sieht nur einen lokalen Unix-Socket; ein rootseitiger Executor besitzt
die für Repository, Docker, Modelle, Git und Recovery notwendigen Rechte. Neben
strukturierten Operationen bietet er ein breites, ausgabebegrenztes Terminal für
neue Aufgaben, einschließlich SSH zu konfigurierten Zielsystemen. Serverseitig
gesperrt bleiben Strombefehle sowie Änderungen an Athenas SSH, LAN, WireGuard,
Firewall, Boot, Kernel, Mounts und Partitionen. Diese Grenze schützt die
Erreichbarkeit des physisch entfernten Hosts.
## Schreibaktionen
Persistente oder destruktive Änderungen folgen immer: Bestandsaufnahme,
exakte Vorschau, an die Vorschau gebundene Freigabe, unveränderte Ausführung,
anschließende Verifikation.
## Vor jedem Push
- Private-Key-, Token-, Passwort- und API-Key-Muster suchen.
- Keine `.env`, Zertifikate, Logs, Bilder, Audio oder Modelle einchecken.
- Beispiele enthalten nur Platzhalter; interne Hostnamen nur wenn bewusst.
- Änderungen am Controller und Netzwerkguard mit Tests und Review versehen.
docs/TOOLING_RELIABILITY_2026-08-24.md
-123
View File
@@ -1,123 +0,0 @@
# Werkzeug-Zuverlässigkeit – Umbau vom 24. August 2026
## Anlass
Mehrere reale Aufgaben scheiterten nicht am Qwen-Modell, sondern an der
Werkzeugschicht: öffentliche Suchen lieferten leere oder veraltete Resultate,
ein rekursiver GitHub-Baum verdrängte die Antwort aus dem Kontext, eine private
Bank-CSV wurde als Knowledge-Quelle statt als Tabelle behandelt und ein nicht
erreichbarer Home-Assistant-Endpunkt provozierte Wiederholungen. Das System
benötigte deshalb kleinere, klarere Werkzeuge und harte Abbruchgrenzen.
## Verbindliche Lösung
1. Allgemeine öffentliche Recherche verwendet Open WebUIs native
`search_web`- und `fetch_url`-Werkzeuge. Für Hermes/Pi steht TinySearch
direkt auf VPN-Port 8203 bereit; der eigene Web-MCP ist nur Rollback.
2. Der offizielle GitHub-MCP bietet genau drei read-only Werkzeuge:
`search_repositories`, `search_code` und `get_file_contents`. Rekursive
Komplettbäume sind ausgeschlossen.
3. Private CSV-/Excel-Dateien werden ausschließlich mit dem lokalen
Code-Interpreter und pandas/openpyxl ausgewertet. Web, MCP und Knowledge/RAG
erhalten keine Dateiinhalte oder daraus abgeleitete Suchbegriffe. Der Filter
leert dafür die MCP-Auswahl und deaktiviert `features.web_search`; im
installierten OpenWebUI-Code läuft der Filter nachweislich vor der
Webwerkzeug-Injektion. Vor `pandas.read_csv` werden Rohvorschau, Kodierung,
Trennzeichen, Kopfzeile, Metadatenzeilen, Dezimal- und Datumsformat erkannt;
damit führen deutsche Bankexporte nicht mehr unnötig zuerst zu einem
ParserError wegen einer falschen Spaltenzahl. Tabellenanalysen sollen im
Regelfall mit einer Erkennungs- und einer Auswertungsrunde auskommen.
4. Pro Antwort sind höchstens 48 interne Werkzeugrunden und 40 tatsächlich
ausgeführte Einzelaufrufe erlaubt. Pro Werkzeugname sind höchstens zwölf
Aufrufe zulässig; identische Argumente dürfen einmal wiederholt werden und
werden beim dritten Versuch unterdrückt. Die zusätzlichen internen Runden sind
Synthesepuffer und erhöhen nicht das Ausführungsbudget. Das abgeleitete,
reproduzierbar gebaute OpenWebUI-Image verwendet die letzte Runde zwingend
als werkzeugfreie Synthese. Erzeugt das Modell trotz entfernter Schemata
noch einmal werkzeugförmige Ausgabe, folgt genau ein zweiter, ebenfalls
werkzeugloser Syntheseversuch. Statt `Tool-call limit reached` ohne Ergebnis
erhält der Benutzer deshalb eine sichtbare Antwort aus den vorhandenen
Befunden samt ehrlicher Angabe fehlender Belege. Inlet-Filter allein können
dies nicht erzwingen, weil sie zwischen OpenWebUIs internen Werkzeugrunden
nicht erneut ausgeführt werden. Seit OpenWebUI-Derivat V7 sitzt die
Größenbegrenzung deshalb direkt in der internen Fortsetzungsschleife: ein
einzelnes Resultat ist auf 12.000, alle Resultate zusammen auf 64.000
Zeichen begrenzt. Zitate und sichtbarer Werkzeugstatus werden zuvor
verarbeitet; das Modell erhält eine markierte Kopf-/Ende-Verdichtung.
Die Basis ist unveränderlich auf OpenWebUI-Revision
`01f4282f1ffe0d6212f58d3afbeae21fffd0c4be` beziehungsweise Image-Digest
`sha256:6a773e5c3a246b65cbe74ce942b294292c0e5f81c138f703d111bc162f7d7c3d`
gepinnt. Das zuvor dokumentierte `v0.9.5` war nicht der tatsächlich
migrierte Datenbankstand und darf für diese Datenbank nicht verwendet werden.
5. Repository-Prüfungen beginnen mit README/Wurzel, verwenden anschließend
gezielte Code-Suchen und öffnen nur relevante Treffer. Eine
konkrete Laufzeitinstanz wird genau einmal über ihr Fachwerkzeug geprüft.
6. Der Home-Assistant-MCP behält den TLS-Namen `ha.casaderoll.de`, routet ihn
im Container aber auf `HOME_LAN_PROXY_IP` im Heimnetz. Dadurch funktioniert
er auch vom Außenstandort über WireGuard.
7. Task-Management ist keine Faktenquelle und wird nicht für einzelne Fragen,
Nachschlageaufgaben oder Dateianalysen verwendet.
8. Mehrdomänen-Aufgaben erhalten automatisch die passenden Fachkataloge und
ein begrenztes Qwen-Reasoning-Budget. Einfache Ein-Domänen-
Aufgaben bleiben im schnellen Non-Thinking-Modus. Alle llama.cpp-Profile
bewahren Reasoning-Zustand zwischen Werkzeugrunden (`--reasoning-preserve`).
9. Wiederkehrende Fachsuchen werden serverseitig gebündelt: Home Assistant
inventarisiert auskommentierte YAML-Blöcke in einem Aufruf; MUA durchsucht
Community Applications mit mehreren Namensvarianten in einem Feed-Durchlauf
und filtert Containerlogs mit mehreren `focus_terms` in einem Aufruf.
10. Offene technische Diagnosen folgen unabhängig vom konkreten Plugin einer
begrenzten Beweiskette: betroffene Komponente und Zeitfenster aus einem
kompakten Status bestimmen, das jüngste exakte Artefakt finden, nur
entscheidende Zeilen lesen und die führende Ursache mit einem zweiten Fakt
bestätigen. MUA r023 begrenzt die Nur-Lese-Shell dafür bereits serverseitig
auf standardmäßig 12.000 Zeichen. Auto Tool Selector 4.7 untersagt als
Standard vollständige Konfigurationsausgaben, rekursive Verzeichnisbäume
und spekulative Shell-Batches. Auslöser war ein realer Appdata-Backup-Test:
Die notwendigen Belege waren vorhanden, wurden jedoch durch eine breite
Konfigurations- und Verzeichnisinventur verdrängt.
## Abnahme
- OpenWebUI-Filtertests: 43
- Web-MCP-Tests: 9
- Athena-Operator-Tests: 13
- Platform-Context-Test: bestanden
- MCP-Katalog-TÜV: Handshake, Toolanzahl, Schema-Größe, Regex-Muster und
verbotene Tools; keinerlei fachliche Toolaufrufe
- Gesamttest des Routers: Profile, Streaming, Tools, Bild, Sprache und
Fehlerwiederherstellung
Der wiederholbare MCP-Test lautet:
```bash
sudo /opt/mike-ai/stack/dev/verify_mcp_catalogs.sh
```
Er muss mit `MCP_CATALOG_SUITE_OK` enden.
## Reale Browserabnahme
Die angemeldete OpenWebUI-Sitzung bestand am 24. August 2026 folgende Läufe:
- unbekannte Website MakerWorld über native Suche plus TinySearch 0.6.1
- GitHub-Repository plus vorhandener Unraid-Container plus Athena-Planung
- mehrstufige Home-Assistant-YAML-Analyse ohne Vollinventar
- bewusst angeforderte 223-KB-Klasse einer Home-Assistant-Zustandsliste; V7
lieferte trotz 2.169 Zuständen nach 30,9 Sekunden eine sichtbare Kurzantwort
## Noch manuell zu prüfen
Ein echter Browsertest mit einer bewusst synthetischen CSV benötigt eine
angemeldete OpenWebUI-Sitzung. Nach Login wird eine harmlose Beispieltabelle
hochgeladen und geprüft, dass die Antwort sichtbare Summen enthält und in der
Werkzeuganzeige ausschließlich lokale Datei-/Codewerkzeuge erscheinen. Für
diesen Test dürfen niemals echte Bankdaten verwendet werden.
## Rollback
Vor dem Live-Umbau liegt die Quell- und Konfigurationssicherung unter
`/data/mike-ai-recovery/pre-tooling-upgrade-20260823-235527`. OpenWebUIs
Datenbank wurde zusätzlich unmittelbar vor Filter- und Modellinstallation
gesichert. Ein Rollback betrifft ausschließlich Werkzeug-/OpenWebUI-Dateien;
Netzwerk, SSH, WireGuard, Kernel, GPU-Treiber und Bootkonfiguration wurden nicht
verändert.
docs/TOOL_ARCHITECTURE_2026-08-24.md
-115
View File
@@ -1,115 +0,0 @@
# Werkzeugarchitektur ab 24. August 2026
## Ziel
Athena darf nicht für jede neue Website oder jede neue Verwaltungsaufgabe ein
neues Werkzeug benötigen. Die Plattform stellt deshalb breite Grundfähigkeiten
bereit und ergänzt sie nur dort durch Fach-MCPs, wo eine strukturierte API einen
echten Vorteil bietet.
## Die drei Ebenen
1. **Breites Web:** OpenWebUI hält `search_web` und `fetch_url` in allen
normalen Profilen verfügbar. MakerWorld, eBay, Herstellerseiten oder eine
morgen neu entstehende Website benötigen keine Selector-Änderung. Für
Hermes, Pi und andere MCP-Clients liegt derselbe allgemeine Einsatzzweck über
den unveränderten TinySearch-Upstream-MCP auf VPN-Port 8203 bereit.
2. **Breiter Operator:** Der Athena Operator enthält neben strukturierten
Plattformaktionen ein ausgabebegrenztes allgemeines Terminal. Es deckt
Docker, Compose, Dateien, Git, HTTP/API, Modellarbeit und SSH zu
konfigurierten Zielsystemen ab. Eine kleine serverseitige Sperre verhindert
ausschließlich Strombefehle und Änderungen an Athenas SSH, LAN, WireGuard,
Firewall, Boot, Kernel, Mounts und Partitionen, weil Athena physisch nicht
erreichbar ist.
3. **Fach-MCPs:** Home Assistant, MUA/Unraid, ARR, Navidrome und GitHub bleiben
erhalten. Sie liefern kurze strukturierte Ergebnisse und domänenspezifische
Schreibabläufe. Sie sind der bevorzugte Weg, aber keine Schranke: Fehlt eine
Spezialoperation, darf der Operator die Aufgabe allgemein erledigen.
OpenWebUI ist Oberfläche und Komfortschicht. Der Auto Tool Selector hält Web
bereit und hängt anhand der Anfrage passende Fachkataloge an. Er verweigert
keine Fähigkeit und erfordert keine Site-spezifischen Regeln. Alle zentralen
MCPs sind über feste WireGuard-Ports auch für Hermes und Pi erreichbar.
Der verbindliche client-unabhängige Mindeststandard ist in
`docs/CLIENT_TOOL_STANDARD.md` festgelegt: allgemeines Web, Athena Operator und
Plattformwissen werden in jedem vertrauenswürdigen VPN-Client konfiguriert.
OpenWebUI darf diese Grundfähigkeiten zur Kontextoptimierung automatisch
auswählen; Hermes und Pi entdecken sie direkt über die MCP-Endpunkte. Die
Sicherheitsgrenze liegt immer serverseitig und hängt nicht von einem Filter ab.
Marketplace-Recherche bleibt ebenfalls allgemein: Der Selector erkennt
Kauf-, Angebots-, Preis- und Versandsuchen unabhängig von einer einzelnen
Website. Qwen beginnt mit einer fokussierten Suche, nutzt höchstens zwei
Reformulierungen, bevorzugt bei blockierten Detailseiten öffentliche Such- und
Kategorieseiten, dedupliziert Artikelnummern und beendet eine normale Suche
nach ungefähr drei Such- und fünf Abrufschritten. Ein Angebot gilt nur mit
aktuellem Preis-, Laufzeit-, Gebots- oder Kaufbeleg als aktiv.
OpenWebUI V8 setzt diese Marketplace-Grenze request-lokal technisch durch:
höchstens drei Suchoperationen über beide allgemeinen Engines zusammen und
höchstens fünf Seitenabrufe. Andere Aufgaben behalten das allgemeine
40-Aufrufe-Budget.
## Agentische Grenzen
- maximal 48 interne Werkzeugrunden
- maximal 40 tatsächlich ausgeführte Einzelaufrufe
- maximal 12 Aufrufe desselben Werkzeugnamens
- identischer Werkzeugname mit identischen Argumenten darf einmal wiederholt
werden; der dritte identische Aufruf wird unterdrückt
- ein unterdrückter Parallelaufruf beendet nicht mehr die gesamte Recherche,
solange im selben Stapel noch sinnvolle Aufrufe vorhanden sind
- bei ausgeschöpftem Budget folgt zwingend eine werkzeugfreie, sichtbare
Schlussantwort aus den bereits erhobenen Befunden
- Werkzeugausgaben bleiben kurz: 12.000 Zeichen je Ergebnis und 64.000 Zeichen
über den Verlauf. Die Begrenzung sitzt in OpenWebUIs interner
Fortsetzungsschleife und greift daher auch auf Resultate, die erst nach dem
ersten Modellschritt entstehen.
Damit stoppt die Plattform bewiesene Schleifen, nicht normale lange Recherche.
Die früheren Grenzen von zwölf Gesamtaufrufen und vier Aufrufen je Werkzeug
waren für Qwen3.8-Agentenaufgaben zu klein.
## Webwege
| Client | Standardweg |
|---|---|
| OpenWebUI | native `search_web` und `fetch_url`, immer verfügbar |
| Hermes/Pi/andere MCP-Clients | `http://192.168.1.212:8203/mcp` (TinySearch; laufender Alt-Gateway zusätzlich 8211 bis zum nächsten geplanten WireGuard-Neustart) |
| Spezial-/Rollbackbedarf | historischer `mcp-web` nur mit Compose-Profil `legacy-web` |
TinySearch stellt die vier Upstream-Werkzeuge `search`, `scrape_urls`,
`research` und `get_current_datetime` bereit. Die frühere selbstgeschriebene
Web-Fassade wird nicht mehr standardmäßig gestartet und liegt nur für Rollback
im Repository.
## Sicherheitsgrenze
Über die WireGuard-Adresse sind die Dienste normal nutzbar. Auf der physischen
Universitätsadresse bleiben UI, Router und MCP-Ports geschlossen. Die
Terminal-Sperre schützt ausschließlich die entfernte Erreichbarkeit; sie ist
kein allgemeiner Funktions- oder Internetfilter.
## Abnahme
Nach Änderungen müssen mindestens folgende Prüfungen erfolgreich sein:
1. `python3 dev/test_openwebui_filters.py`
2. `python3 dev/test_athena_operator.py`
3. `docker compose -f compose.yaml config -q`
4. `docker compose -f platform/mcp/compose.yaml config -q`
5. `dev/verify_mcp_catalogs.sh`
6. Browserlauf mit einer unbekannten öffentlichen Website, GitHub plus
Laufzeitprüfung sowie einer mehrstufigen Home-/Unraid-Aufgabe
Produktive Abnahme am 24. August 2026:
- MakerWorld ohne Site-Adapter: 12 Werkzeugaufrufe, verifizierter Treffer mit
Downloadzahl und Direktlink, sichtbare Antwort nach 102,5 Sekunden
- GitHub + Unraid + Athena: 12 gezielte Repository-Leseaufrufe plus
Laufzeitprüfung; vorhandenen Deemix-Backendcontainer korrekt wiederverwendet
- Home Assistant YAML: drei auskommentierte Automatisierungen gefunden, ohne
vollständige Zustandsliste und mit sichtbarer Abschlussantwort nach 88,0 Sekunden
- absichtlicher Großausgabetest: 2.169 Home-Assistant-Zustände in einem
Werkzeugresultat; durch V7 intern verdichtet und nach 30,9 Sekunden korrekt
mit ausschließlich Anzahl und Testsatz beantwortet
docs/UNRAID_AUTOMATIC_UPDATE_WORKFLOW.md
-105
View File
@@ -1,105 +0,0 @@
# Automatischer Unraid-Docker-Updateablauf
Stand: 24. August 2026
## Ziel
Ein ausdrücklich formulierter Auftrag wie „prüfe die Docker-Updates auf Unraid,
führe bestätigte Updates aus und kontrolliere das Ergebnis“ muss in Open WebUI
ohne manuelles Aktivieren von Werkzeugen vollständig ablaufen.
## Automatische Werkzeugwahl
Der `MikeAI Auto Tool Selector` unterscheidet zwischen Lesen und Ändern:
- reine Status- oder Updatefragen erhalten nur `mua-readonly-local`;
- eine in der aktuellen Nachricht ausdrücklich verlangte Unraid-Änderung erhält
`mua-readonly-local` und `mua` gemeinsam;
- Formulierungen wie „nur prüfen“ oder „keine Änderungen“ unterdrücken den
Verwaltungszugang;
- die bereitgestellten Verbindungen sind keine allgemeine Freigabe. Der Auftrag
muss die konkrete Änderung selbst enthalten.
Der vorgesehene Ablauf lautet immer:
1. Zustand und Kandidaten read-only erfassen.
2. Die engste gebündelte Änderung ausführen.
3. Das Ergebnis read-only oder durch die gebündelte technische Verifikation
kontrollieren.
## Verbindliches Batch-Werkzeug
MUA r019 stellt `unraid_docker_update_verified_batch` bereit. Das Werkzeug
akzeptiert 1 bis 25 exakte, mit `|` getrennte Containernamen.
Für jeden Container liest es zunächst Container-ID, Image-ID und Laufzustand.
Danach zieht es das im Unraid-Benutzertemplate konfigurierte Image und
vergleicht die unveränderliche lokale Image-ID. Bereits aktuelle Container
werden vollständig übersprungen – auch wenn Unraids Statuscache noch ein Update
meldet. Nur bei tatsächlich geänderter Image-ID wird neu erstellt. Laufend
bleibt laufend, gestoppt bleibt gestoppt.
Die kompakte Nachkontrolle enthält Container- und Image-ID-Änderung,
Endzustand, RestartCount und Healthcheck-Status. Templates, Ports, Volumes und
Netzwerke werden nicht verändert. Eine vorhandene Freigabe des bisherigen
Einzelwerkzeugs `unraid_docker_update` aktiviert nach dem Upgrade automatisch
auch die sicherere Batch-Variante.
## Idempotenz
Der Cache `/var/lib/docker/unraid-update-status.json` ist nur ein
Kandidatenhinweis. Er darf nie allein eine Neuerstellung auslösen. Autoritativ
ist der Image-ID-Vergleich nach dem Pull.
Die Unraid-Weboberfläche und mobile Ansichten lesen weiterhin diesen separaten
Cache. Ein technisch verifizierter Pull/Rebuild aktualisiert dessen Anzeige
nicht zwingend sofort. Deshalb kann dort weiterhin „Apply Update“ stehen,
obwohl der lokale Image-ID-Vergleich bereits `already-current` ergeben hat.
Für eine frische Anzeige muss Unraids eigener Statuslauf
`dynamix.docker.manager/scripts/dockerupdate check` abgeschlossen sein. Das ist
eine Aktualisierung der Anzeige und kein erneuter Container-Rebuild.
Auch nach diesem nativen Statuslauf kann Unraid einzelne Images weiterhin als
Update markieren, obwohl Container-Image-ID und lokale Tag-Image-ID identisch
sind. Das kommt insbesondere bei Registry-/Manifest- und Multiarch-Digest-
Vergleichen vor. In diesem Konfliktfall ist das Ergebnis von
`unraid_docker_update_verified_batch` nach dem Pull maßgeblich: identische
unveränderliche Image-IDs bedeuten `already-current`; ein weiterer Rebuild nur
zum Entfernen der GUI-Anzeige ist weder nötig noch erwünscht. Die GUI-Meldung
ist dann ausdrücklich als Fehlanzeige zu melden.
Ein wiederholter Lauf muss bei einem aktuellen Image folgendes melden:
```text
result: already-current
recreated: false
container_id_changed: false
image_id_changed: false
```
## Produktiver Regressionstest vom 24. August 2026
Ein neuer Open-WebUI-Chat erhielt ohne manuelle Werkzeugauswahl den Auftrag,
Unraid-Docker-Updates zu prüfen, bestätigt auszuführen und nachzukontrollieren.
- automatisch bereitgestellt: MUA read-only plus MUA-Verwaltung;
- zwei read-only-Aufrufe für Update-Status und Containerbestand;
- genau ein gebündelter Aufruf für fünf Kandidaten;
- alle fünf als `already-current` erkannt;
- null Neuerstellungen und null Container-/Image-ID-Änderungen;
- AirConnect blieb laufend; Virtual-DSM, AzuraCast, WindowsXP und Windows11
blieben gestoppt;
- `all_verified: true`.
Der vorherige Ablauf benötigte mehrere Benutzernachrichten und vier bis fünf
einzelne Update-Aufrufe. Dieser Pfad ist ersetzt.
## Recovery-Prüfung
1. MUA-Health muss r019 oder neuer melden.
2. Open WebUI muss den Auto Tool Selector 3.3.0 oder neuer enthalten.
3. „Gibt es Docker-Updates auf Unraid? Nur prüfen“ darf nur MUA read-only
bereitstellen.
4. Ein ausdrücklich schreibender synthetischer Auftrag muss beide MUA-Zugänge
bereitstellen und das Batch-Werkzeug wählen.
5. Ein Wiederholungstest mit aktuellem Image darf keine Neuerstellung auslösen.
docs/UNRAID_MEDIA_AUDIT_WORKFLOW.md
-58
View File
@@ -1,58 +0,0 @@
# Automatische Medienbestandsprüfung auf Unraid
Stand: 24. August 2026
## Zweck
Lokale Medienbestände können in einem Open-WebUI-Auftrag mit einer offiziellen
Online-Liste verglichen werden, ohne dass der Benutzer Werkzeuge nachträglich
einschaltet. Der Ablauf bleibt vollständig read-only.
## Werkzeugwahl
Der Auto Tool Selector 3.5 erkennt einen ausdrücklich lesenden Unraid-Auftrag
und stellt ausschließlich `mua-readonly-local` bereit. Wörter wie „Folgen
fehlen“ oder „Hörspielserie“ aktivieren nicht mehr fälschlich Sonarr/Radarr.
Formulierungen wie „ohne Änderungen“, „ohne Downloads“ und „keinerlei
Änderungen“ verhindern zuverlässig die Auswahl von MUA-Admin.
Verlangt derselbe Auftrag aktuelle Online- oder Streaming-Belege, aktiviert der
Selector zusätzlich Open WebUIs native Werkzeuge `search_web` und `fetch_url`.
Damit ist MUA plus Websuche ein einziger automatischer Mischauftrag; der alte
Web-MCP wird dafür nicht benötigt.
## Dateiinventar
MUA r021 stellt `unraid_files_inventory` bereit. Das Werkzeug liest keine
Dateiinhalte und akzeptiert ausschließlich einen vorhandenen Unraid-Share plus
einen relativen Pfad unterhalb dieses Shares. Pfadtraversal, absolute Pfade und
Symlink-Verfolgung sind gesperrt. Tiefe, Trefferzahl und Zahl der untersuchten
Einträge sind begrenzt.
Empfohlener Ablauf:
1. `unraid_shares_list` nur dann verwenden, wenn der Share unbekannt ist.
2. Mit `unraid_files_inventory`, `name_contains` und nur Verzeichnissen die
passende Sammlung lokalisieren.
3. Den exakten zurückgegebenen `relative_path` in einem zweiten Aufruf ohne
Namensfilter inventarisieren.
4. Aus Dateinamen lokale Nummern/Titel extrahieren.
5. Offizielle Liste über native Websuche ermitteln und Differenz bilden.
6. Fehlende Titel beim gewünschten Anbieter gezielt verifizieren.
7. Fakten, Dateinamen-Schlussfolgerungen und Unsicherheiten getrennt ausgeben.
Die generische Nur-Lese-Shell ist nur ein Fallback, wenn das Inventarwerkzeug
die konkrete Frage nicht beantworten kann. Wiederholte `ls`/`find`-Ketten sind
für Bibliotheksprüfungen nicht vorgesehen.
## Regressionstest
Der ursprüngliche Lauf zur Reihe „Die drei ???“ brauchte nach dem Share-Fund
vier einzelne Shell-Aufrufe und verbrauchte das Werkzeugbudget vor dem
eigentlichen Datei- und Webabgleich. Dieser Fall ist der verbindliche
Regressionstest für Selector 3.5 und MUA r021:
- automatisch nur MUA read-only;
- höchstens zwei Inventaraufrufe für Lokalisierung und Bestand;
- danach native Webrecherche;
- keine Rückfrage, kein Download und keine Dateisystemänderung.
docs/VPN_SERVICE_PORTS.md
-40
View File
@@ -1,40 +0,0 @@
# Dienste direkt über das Heim-VPN
Athena behandelt die von der Fritzbox zugewiesene WireGuard-Adresse als ihr
normales Anwendungsnetz. OpenWebUI, die Router-API und die nützlichen
Werkzeugdienste sind dort direkt erreichbar. Auf der physischen
Universitätsadresse werden diese Ports nicht veröffentlicht.
Aktuelle VPN-Adresse: `192.168.1.212`
| Port | Dienst | Adresse |
|---:|---|---|
| 22 | SSH zum Athena-Host | `ssh root@192.168.1.212` |
| 8080 | OpenWebUI | `http://192.168.1.212:8080` |
| 8081 | OpenAI-kompatible Router-API | `http://192.168.1.212:8081/v1` |
| 8085 | TTS-Gateway | `http://192.168.1.212:8085` |
| 8091 | Piper direkt | `http://192.168.1.212:8091` |
| 8092 | XTTS direkt | `http://192.168.1.212:8092` |
| 9119 | Hermes Dashboard | `http://192.168.1.212:9119` |
| 8642 | Hermes Agent API | `http://192.168.1.212:8642` |
| 8787 | optionale Hermes Community-WebUI | `http://192.168.1.212:8787` |
| 8201 | Athena Platform Context MCP | `http://192.168.1.212:8201/mcp` |
| 8202 | Athena Operator MCP einschließlich Terminal | `http://192.168.1.212:8202/mcp` |
| 8203 | Allgemeiner TinySearch-MCP | `http://192.168.1.212:8203/mcp` |
| 8204 | GitHub-MCP | `http://192.168.1.212:8204/mcp` |
| 8205 | Home-Assistant-MCP | `http://192.168.1.212:8205/mcp` |
| 8206 | ARR-MCP | `http://192.168.1.212:8206/mcp` |
| 8207 | Navidrome-MCP | `http://192.168.1.212:8207/mcp` |
| 8208 | Unraid-SSH-MCP, falls aktiviert | `http://192.168.1.212:8208/mcp` |
| 8210 | SearXNG-Diagnoseoberfläche | `http://192.168.1.212:8210` |
| 8211 | TinySearch-MCP direkt | `http://192.168.1.212:8211/mcp` |
Pi, Hermes und andere MCP-Clients tragen diese URLs direkt ein. Ein
zusätzliches MCP-Gateway ist nicht erforderlich. Nicht gestartete optionale
Container führen am jeweiligen Port lediglich zu einer nicht erreichbaren
Verbindung; nach ihrem Start funktioniert derselbe Port automatisch.
Die Portweiterleitungen laufen ausschließlich im Netzwerk-Namespace des
WireGuard-Containers und binden explizit an dessen VPN-Adresse. Deshalb sind
sie nicht über `172.21.117.202` erreichbar. SSH bleibt davon unabhängig auch
auf der Universitätsadresse zulässig.
docs/WIREGUARD_HOME_PEER.md
-57
View File
@@ -1,57 +0,0 @@
# WireGuard über die Fritzbox
## Gewählter Betriebsmodus
Athena verwendet die Fritzbox-Konfiguration für **einen einzelnen
WireGuard-Client**. Die unveränderte Exportdatei wird als root-only Secret nach
```text
/etc/mike-ai/wireguard/fritz-athena.conf
```
kopiert (`chmod 600`). Sie gehört weder ins Git-Repository noch in Backups ohne
Verschlüsselung. Eine LAN-zu-LAN-Konfiguration ist für diesen Host nicht nötig.
Der Tunnel endet im Container `mike-ai-wireguard-gateway`. Nur dieser Container
erhält `NET_ADMIN` und `/dev/net/tun`. Open WebUI und Router veröffentlichen
keine Ports auf der physischen Hostadresse. Der Gateway stellt OpenWebUI,
Router und die Werkzeugdienste auf der von der Fritzbox zugeteilten
VPN-Adresse bereit. Die vollständige Liste steht in
[VPN_SERVICE_PORTS.md](VPN_SERVICE_PORTS.md).
## Split der Verantwortlichkeiten
- Debian, Paketverwaltung und SSH benutzen die normale Standortverbindung.
- Die Docker-Netze `frontend` und `tools-egress` werden per Quellrouting zum
WireGuard-Gateway geschickt.
- Interner Docker-Verkehr bleibt lokal und durchquert den Tunnel nicht.
- Der Fritzbox-Export darf `0.0.0.0/0` und `::/0` enthalten. Das ändert **nicht**
die Default-Route des Debian-Hosts, sondern nur die des Gateway-Namespace.
- Fällt WireGuard aus, bleibt die Quellroute auf den dann unerreichbaren
Gateway zeigen: Anwendungscontainer fallen geschlossen aus.
## Kontrolle ohne Geheimnisse auszugeben
```bash
docker inspect -f '{{.State.Health.Status}}' mike-ai-wireguard-gateway
docker exec mike-ai-wireguard-gateway wg show wg0 latest-handshakes
systemctl status mike-ai-container-vpn-guard
```
Der Healthcheck verlangt einen Handshake, der jünger als drei Minuten ist.
Open WebUI liegt unter `http://<VPN-IP>:8080`, der Router unter
`http://<VPN-IP>:8081/v1`; die MCPs liegen auf 8201 bis 8208. An der
physischen Standortadresse dürfen diese Anwendungsports nicht antworten.
## Getestetes Verhalten am 22. August 2026
- Fritzbox-Handshake und Datenverkehr in beide Richtungen: erfolgreich
- Open WebUI, Router und direkte MCP-Endpunkte über die VPN-Adresse: erreichbar
- dieselben Ports über die physische Hostadresse: geschlossen
- VPN-Gateway gestoppt: ausgehender Open-WebUI-Test blockiert (fail-closed)
- Gateway erneut gestartet: automatischer aktueller Handshake
- vollständiger Hostneustart: SSH, Guard, Gateway, Open WebUI und Router kamen
automatisch gesund zurück; VPN-Ports erreichbar, Standortports geschlossen
Die Exportdatei muss Bestandteil des verschlüsselten Disaster-Recovery-Satzes
sein. Ohne sie kann ein neuer Host den Heimtunnel nicht rekonstruieren.
docs/XTTS_EVALUATION_2026-08-23.md
-113
View File
@@ -1,113 +0,0 @@
# XTTS-v2 GPU evaluation on Athena (2026-08-23)
## Purpose and safety boundary
This was an isolated, reversible evaluation of Coqui XTTS-v2 as a possible
replacement for Piper. The user accepted the Coqui Public Model License for
this private test.
- Official image: `ghcr.io/coqui-ai/xtts-streaming-server:latest-cuda121`
- Pulled digest: `sha256:f7fb3b1f9d4bc88af94da1b5959d8002f1e0b003c97557164034eb8a29f01b90`
- Test container: `mike-ai-xtts-test`
- GPU visibility: RTX 3060 only
- Host binding: `127.0.0.1:18105` only
- Restart policy: `no`
- Model cache: `/data/xtts-test/cache`
- Piper, Open WebUI and the router were not reconfigured.
The official server describes itself as a demo server. In particular, it does
not support concurrent streaming requests and is not an OpenAI-compatible
production endpoint. A queueing/OpenAI compatibility proxy is therefore
required before integration with Open WebUI.
## XTTS resource use
With the Medium profile already running, XTTS increased RTX 3060 use from
about 4,471 MiB to about 6,419 MiB. XTTS therefore occupied approximately
1,948 MiB and left about 5,492 MiB free. It did not use the RTX 5080.
With Ultra (256K) and XTTS loaded together:
| GPU | Used | Free |
|---|---:|---:|
| RTX 3060 12 GB | 8,669 MiB | 3,242 MiB |
| RTX 5080 16 GB | 15,770 MiB | 89 MiB |
The combination loaded successfully without OOM. This confirms that XTTS fits
even beside the largest standard text profile. The RTX 5080 must remain
unavailable to XTTS because Ultra already fills it almost completely.
## Streaming measurements
The initial measurements used built-in female speaker `Ana Florence`. A
subsequent five-voice German comparison selected **`Annmarie Nele`** as the
production voice. Tests used harmless synthetic text.
| Test | First audio | Generation time | Produced audio | RTF |
|---|---:|---:|---:|---:|
| German | 0.701 s | 2.889 s | 6.965 s | 0.415 |
| English | 0.305 s | 1.330 s | 3.989 s | 0.333 |
| German sentence with English IT terms | 0.309 s | 2.496 s | 7.339 s | 0.340 |
After warm-up, audio starts after roughly 0.3 seconds and synthesis is around
2.4 to 3 times faster than real time. Perceived Open WebUI latency also
includes Qwen's time to finish the first sentence and proxy buffering.
## Effect on Qwen throughput
| Profile | XTTS state | Generation speed |
|---|---|---:|
| Medium 160K | loaded but idle | 71.92 token/s |
| Medium 160K | actively speaking | 59.90 token/s |
| Ultra 256K | loaded but idle | 66.89 token/s |
| Ultra 256K | actively speaking | 55.27 token/s |
Active synthesis costs roughly 17% of Qwen generation speed because Qwen also
uses the RTX 3060. The slowdown ends with the speech request. Merely keeping
XTTS resident did not cause instability.
## Result and recommendation
XTTS-v2 is technically viable on the RTX 3060 and fits alongside every current
profile, including Ultra 256K. It provides early streaming and substantially
more natural multilingual speech than the current German-only Piper voice.
The production design keeps Piper and adds a small internal proxy that provides:
1. OpenAI-compatible `/v1/audio/speech` input and output.
2. A one-request queue because the official XTTS server has no concurrency.
3. German/English text segmentation so English product names are synthesized
with `language=en` while surrounding German remains `language=de`.
4. Cached speaker conditioning and a fixed allowlist of voices.
5. Health checks, bounded timeouts and automatic fallback to Piper.
This gateway now lives under `platform/docker/tts-gateway/`. The externally
visible compatibility values remain `model=piper` and `voice=alloy`; internally
that alias selects `Annmarie Nele` whenever XTTS is healthy.
## Production result and rollback
After the isolated evaluation, the compatibility gateway was tested in three
stages and then deployed to production:
1. Healthy XTTS produced valid WAV through the router-compatible endpoint.
2. XTTS was deliberately stopped; the same endpoint returned valid Piper WAV.
3. XTTS was restarted and automatically became the active backend again.
The production services are `mike-ai-xtts` and `mike-ai-tts-gateway`, both
Docker-internal. Piper remained healthy throughout. OpenWebUI required no
configuration or database change. The router's public compatibility values
remain `model=piper` and `voice=alloy`.
The initial Compose GPU declaration exposed both NVIDIA cards and caused XTTS
to select the nearly full RTX 5080. This was caught before the router switch.
The final declaration uses a Docker device reservation with the stable RTX
3060 UUID; inspecting the container must show exactly that UUID in
`DeviceRequests`.
The verified pre-deployment state is backed up below
`/data/backups/mike-ai/20260823-xtts-production`. The reusable rollback helper
is `platform/scripts/rollback-tts-production.sh`; it restores the saved Compose
and environment files, recreates the old Piper-connected router and removes
only XTTS and its gateway. Both VPN and university-network SSH paths were
verified after deployment.
docs/qwen38-fast-profile-benchmark-2026-08-20.md
-46
View File
@@ -1,46 +0,0 @@
# Qwen3.8-27B Fast-Profil-Test vom 20. August 2026
Hardware: RTX 5080 mit 16 GB VRAM. Modell: `Qwen3.8-27B-IQ4-MIX.gguf`.
## Ergebnis
Gewinner ist das Profil mit 76.800 Tokens Kontext, MTP2, Haupt-KV-Cache in Q4_0,
MTP-Draft-KV in F16 und einem nicht auf die GPU ausgelagerten BF16-Vision-Projektor.
| Profil | Kontext | Kurztests TG | 30K belegt | 66K belegt | Vision | Stabilität |
| --- | ---: | --- | ---: | ---: | --- | --- |
| bisher: Draft-Q4 | 73.728 | 85,6 / 93,6 / 98,3 t/s | nicht gemessen | nicht gemessen | nein | stabil |
| Draft-F16 | 73.728 | 92,7 / 100,5 / 103,4 t/s | nicht gemessen | nicht gemessen | nein | stabil |
| Gewinner | 76.800 | 94,3 / 103,3 / 114,7 t/s | 91,5 t/s | 72,0 t/s | ja, CPU-Projektor | stabil |
| BeeLlama KVarN4/3 | 98.304 | 82,9 / 98,2 / 90,2 t/s | nicht erreicht | nicht erreicht | nein | CUDA-OOM beim großen Prefill |
| BeeLlama KVarN4/3 | 90.112 | Kurztest nicht wiederholt | nicht erreicht | nicht erreicht | nein | CUDA-OOM beim großen Prefill |
Die realistischen drei Kurztests waren deutsche Analyse, Python-Code und strukturiertes JSON
mit jeweils bis zu 1.200 Ausgabetokens. Große Kontexttests verwendeten ausschließlich
synthetischen Fülltext.
## Wichtige Erkenntnisse
- Der F16-Draft-Cache benötigt bei diesem einlagigen MTP weniger VRAM als der quantisierte
Q4-Draft-Cache. Bei 73.728 Tokens stieg der freie VRAM von ungefähr 64 auf 168 MiB.
- 81.920 Tokens waren mit MTP nicht startfähig. 76.800 Tokens starteten und bestanden einen
Prefill mit ungefähr 66.000 synthetischen Tokens.
- Nahe dem vollen Kontext sinkt die Ausgabe trotz unverändertem Profil unter 80 t/s. Bei
ungefähr 30.000 belegten Tokens wurden noch 91,5 t/s erreicht, bei etwa 66.000 Tokens
72,0 t/s. Das ist der zunehmende Attention-Aufwand, kein CPU-Offload.
- Der 931-MB-BF16-Vision-Projektor bleibt mittels `--no-mmproj-offload` im System-RAM.
Dadurch bleibt der VRAM-Verbrauch des Sprachmodells praktisch unverändert. Das synthetische
Testbild wurde korrekt erkannt; Bild-Prefill etwa 2,5 Sekunden, Ausgabe etwa 92–94 t/s.
- KVarN war in kurzen Tests vielversprechend, stürzte aber bei großen Prefills reproduzierbar
im CUDA-Flash-Attention-Kernel mit OOM ab und ist daher nicht produktionsgeeignet.
## Aktives Fast-Profil
Siehe `platform/profiles/profile-fast.conf`. Wichtige Parameter:
- `--ctx-size 76800`
- `--cache-type-k q4_0 --cache-type-v q4_0`
- `--spec-draft-type-k f16 --spec-draft-type-v f16`
- `--spec-draft-n-max 2`
- `--mmproj .../mmproj-BF16.gguf --no-mmproj-offload`
- vollständiger GPU-Offload der Modellgewichte auf `CUDA0`
docs/qwen38-pure-256k-benchmark-2026-08-22.md
-32
View File
@@ -1,32 +0,0 @@
# Qwen3.8 Pure – 256K-Validierung vom 22. August 2026
## Aufbau
- Modell: `jpetrina/Qwen3.8-27B-IQ4_XS-pure-GGUF`
- Datei: `qwen3.8-27b-IQ4_XS-pure.gguf`
- SHA-256: `ea5a3c45d407f9b9e5d2c0d647f0ea600f486f6b86b92b56d0823ba073dae675`
- Kontext: 262.144 Tokens
- GPUs: RTX 5080 + RTX 3060, Layer-Split 80:20
- KV-Cache: Q4_0 für K und V
- MTP: aktiviert, maximal zwei Draft-Tokens
- Vision-Projektor: aus
Der Test verwendete ausschließlich synthetische Daten. Es wurden keine Chats,
MCP-Antworten oder Nutzerdaten gelesen.
## Ergebnis
| Messung | IQ4_XS Pure | IQ4-MIX Referenz |
|---|---:|---:|
| Laden erfolgreich | ja | ja |
| Kurzer Ausgabetest | 68,19 Tok/s | 59,15 Tok/s |
| 220.190-Token-Prefill | 368,64 Tok/s | 357,86 Tok/s |
| Ausgabe nach 220K Prompt | 26,76 Tok/s | 26,32 Tok/s |
| Dauer des 220K-Tests | 599,91 s | 617,95 s |
| Sentinel wiedergefunden | ja | ja |
| OOM/Absturz | nein | nein |
Pure war im kurzen Ausgabetest rund 15,3 Prozent schneller. Beim fast vollen
Kontext war die Ausgabegeschwindigkeit beider Varianten nahezu gleich. Da Pure
den vollständigen Langtest bestanden hat, ist es das ausgewählte Ultra-Profil.