Athena-Deck/README.md

# Athena Deck · Router 0.7

Eigenständige Oberfläche mit Python und HTML/CSS/JavaScript. Python >= 3.10;
verschlüsselte Backups benötigen `python3-cryptography` (im Docker-Installer enthalten). Kein Frontend-Build nötig.

Die Navigation beginnt mit dem [Dashboard](DASHBOARD.md). Es zeigt die
Live-Telemetrie und die aus dem alten Athena-Dashboard übernommene History;
die frühere separate Hardware-Seite wurde entfernt.

## Navigation und Detailansichten

Die **Übersicht** enthält Dashboard und Steuerung (Endpunkt und GPU-Modi).
**KI-Werkzeuge** trennt Chat & Sprachmodelle, Bildgenerierung, Musikgenerierung,
Sprachausgabe, Spracherkennung, Stimmwerkzeuge und Videogenerierung.
Zusätzliche Oberflächen stehen unter **Anwendungen → Weitere Dienste**.

Unter **Einstellungen → Laufzeiten** führt eine aufklappbare Liste zu den
Installations-, Versions- und Statusseiten. Der Laufzeiten-Katalog zeigt den
aktuellen Installationsstatus, lässt sich nach Name und Bereich filtern und
bietet eine direkte llama.cpp-Releaseprüfung mit Änderungsnotizen. „Build
vorbereiten“ übernimmt das Release in das Buildformular; erst dessen
Bestätigung startet den Build. Audio Separator besitzt einen eigenen Installer und WAV-Trenntest. Unterstützte
BS-/MelBand-RoFormer-Pakete werden einschließlich passender YAML-Konfiguration
geladen; ungeprüfte Hub-Dateien werden dadurch nicht freigeschaltet. Die einzelnen Laufzeiten stehen
nicht mehr separat in der Seitenleiste. Bibliothek und Profile verwenden
kompakte, aufklappbare Zeilen. Bibliotheken gruppieren die Dateien nach Hauptgewichten, Vision-/Audio-Projektoren, Textencodern, VAE, Konfigurationen und weiteren Zusatzkomponenten; nur vorhandene Gruppen werden angezeigt. Unbekannte Rollen bleiben separat sichtbar. In den Zeilen: Details, API-Freigabe, Komponenten und Aktionen
stehen in der geöffneten Zeile. Downloads behalten Fortschritt, Geschwindigkeit,
Restzeit und Warteschlangenaktionen. Der laufende Betrieb wird zentral unter
**Steuerung** angezeigt; Testbereiche behalten ihre jeweiligen Formulare.
Bestehende URL-Fragmente bleiben gültig.

## Vorläufige Testinstallation auf Debian

Zielprodukt: nativer systemd-Dienst auf Debian. Der derzeitige Docker-Installer dient ausschließlich der isolierten Testphase.

Ein eigenständiger Testinstaller ohne WireGuard ist vorhanden: [Debian-Installation](INSTALL.md).
Auf dem Zielserver: `sudo ./install.sh --check`, anschließend `sudo ./install.sh --install`.
Vorhandenes Docker wird vorausgesetzt; produktive Dienste werden nicht verändert.

## Neu: Modellverwaltung und llama.cpp-Einstellungen

Katalog, Datei-Downloads, Bibliothek, serverseitig gespeicherte Profile und
llama.cpp-Buildverwaltung sind live. Der Download-Reiter erlaubt das Ausblenden
abgeschlossener Einträge ohne Dateiverlust. Entdecken zeigt Größen und eine
konservative Gewichts-Speicherprüfung; noch keine vollständige Laufzeitprognose.
Bildprofile mit vollständigem Qwen-Image-2.1-GGUF-Rezept lassen sich unter „Testen“ ausführen. Textprofile sind am eigenen [OpenAI-kompatiblen Endpunkt](ENDPOINT.md) ausführbar. Qwen3-TTS CustomVoice ist über eine eigene CUDA-Laufzeit ausführbar; Qwen3-ASR bietet Spracherkennung; Musik, Voice und Video bleiben vorbereitet. Sprachmodelle besitzen außerdem einen internen Testchat mit Abbruch und Speicherdiagnose. Details: [Modellverwaltung](STUDIO.md).

Der Bildtest und `/v1/images/edits` akzeptieren beim geprüften Qwen-Image-2.1-Rezept
bis zu vier Referenzbilder. Die Zahl wird pro aktivem Modellrezept angezeigt;
andere Bildmodelle erhalten keine ungeprüfte Edit-Fähigkeit.

Entdecken und Bibliothek zeigen die aus Hugging-Face-Metadaten erkennbare
Modellfamilie und den Status der vorhandenen Laufzeit. Bei unbekannten
Bildvarianten kann Deck eine vorhandene ComfyUI-Installation als mögliche Basis
anzeigen. Ohne geprüftes Komponentenrezept und Workflow bleibt das Modell
gesperrt; ein weiterer Runtime-Build wird daraus nicht automatisch abgeleitet.

## LTX Original und LTX DeskWEB

Unter **Einstellungen → Laufzeiten → LTX Original** wird das gepinnte originale
LTX-Desktop-Backend separat installiert. Vorhandene Modellgewichte werden
per Dateiansicht wiederverwendet. Im Bereich Video kann zwischen ComfyUI und
LTX Original gewählt werden; LTX DeskWEB benötigt LTX Original. Details:
[LTX Original](LTX_ORIGINAL.md).

## Zugang und API-Token

Beim ersten Öffnen werden Oberflächenkennwort und separater API-Token eingerichtet.
Beide sind unter **Zugang & API** änderbar. Der Debian-Installer richtet den Zugang vor dem Serverstart ein. Details und API-Rechte: [Zugangsverwaltung](ACCESS.md).

## WireGuard-Einstellungen

Das separate [WireGuard-Modul](network/README.md) enthält Conf-Import und
LAN-/Tunnel-Zugriff. In der aktuellen Debian-Entwicklungsinstanz ist es nicht
angebunden; der Zugriff erfolgt über SSH-Tunnel. Der bestehende Gateway bleibt unverändert.

## Zielsystem und Entwicklung

Athena Deck läuft vollständig auf einem Debian-Server mit RTX 5080 und RTX 3060.
Oberfläche, API, Router und Hardware-Erfassung laufen dort. Der Arbeitsplatz
benötigt nur Browser und SSH; er ist kein Anwendungsserver. Auch Builds und
Integrationstests werden auf Athena ausgeführt. Chat- und Qwen-Image-Laufzeiten sind am eigenen Endpunkt angebunden.

Die isolierte Entwicklungsinstallation ist in [DEVELOPMENT.md](DEVELOPMENT.md)
beschrieben. Hardware wird direkt über `/proc`, hwmon und nvidia-smi gelesen;
Deck benötigt dafür keinen SSH-Schlüssel. Der eigene Router ist in [ENDPOINT.md](ENDPOINT.md) dokumentiert.

## Interne API v1

Die GUI verwendet eine sitzungsgeschützte Verwaltungs-API. `GET /api/v1/status`
und `GET /api/v1/hardware` sind auch mit dem separaten API-Token lesbar.
Die Übersicht steuert den eigenen OpenAI-kompatiblen API-Listener; Demo-Dienst
und Demo-Routen wurden entfernt. Port, Profilfreigaben, Inferenzrouten,
Betriebsgrenzen und SSH-Tunnel: **[ENDPOINT.md](ENDPOINT.md)**.

Hardware: `available` bezeichnet Erfolg der Hardware-Abfrage, einzelne
Messwerte können trotzdem fehlen (`null`). Ein Ausfall der Erfassung liefert available=false,
leere Daten und eine Fehlermeldung, keine alten Werte als vermeintliches Livebild.
CPU-Auslastung: 250-ms-Differenz aus `/proc/stat` ohne doppelte Guest-Zählung.
RAM: MemTotal minus MemAvailable aus `/proc/meminfo`, Einheit Bytes.
CPU-Temperatur: k10temp/coretemp temp1_input, Grad Celsius.
GPU: nvidia-smi CSV mit Index, UUID, Name, VRAM in MiB, GPU-Auslastung in Prozent,
Temperatur in Grad Celsius. Keine Zuordnung nach vermuteter GPU-Reihenfolge.
Die Anzeige rechnet Speicher in GiB um. Fehlende Werte heißen „Nicht verfügbar“.
Abfrage mit höchstens einer Sekunde Cache; das Dashboard aktualisiert jede
Sekunde und zeichnet unabhängig von der geöffneten Seite alle 15 Sekunden auf.
Details zur historischen Datenbank stehen in [DASHBOARD.md](DASHBOARD.md).

## Struktur und Grenzen

- `server.py`: Verwaltungs-API und lesende Dashboard-/Hardware-Abfragen.
- `dashboard_data.py` und `dashboard_history.py`: Live-Telemetrie und persistente History.
- `endpoint.py`: separater authentifizierter Inferenz-Listener.
- `inference.py`: native llama.cpp-Prozesse und gemeinsame GPU-Reservierung.
- `image_test.py`: eigene ComfyUI-Aufträge, gemeinsam mit dem Router koordiniert.
- `endpoint-ui.js`: Übersicht, Port und Profilfreigaben.

Sprachmodelle und Qwen-Image-Profile sind ausführbar. Qwen3-TTS CustomVoice ist ebenfalls ausführbar; übrige Audio-/Video-Laufzeiten
bleiben vorbereitet; weitere Docker-Dienste werden nur mit Deck-Labels angezeigt.
Der native systemd-Installer ist noch nicht vollständig; aktuell gilt der isolierte
Docker-Testinstaller. Keine Migration oder Steuerung des bisherigen Routers.

## Verifikation am 28.09.2026

`python3 -m unittest discover -s . -v`: drei Tests erfolgreich.
Zusätzlich GUI-Start → Läuft/Erreichbar → Stopp → Gestoppt/Nicht erreichbar geprüft.
Hardware im Browser mit Ryzen 5 5600, 46,9 GiB RAM, RTX 3060 und RTX 5080 geprüft;
CPU-/GPU-Temperaturen, VRAM und Auslastung vorhanden. Hardware-Ausfall im Test
simuliert, ohne Athena oder SSH zu unterbrechen.
Produktive Router-/Modell-/Bild-/Audio-/Netzwerkdienste nicht verändert.
Vorhandene ungesicherte Änderungen im übergeordneten Repository unangetastet.

### Bildlaufzeit installieren und Profile entfernen

Unter **Einstellungen → Laufzeiten → Bildgenerierung** zeigt Deck die Herkunft
und die festgelegten ComfyUI-/GGUF-Versionen. Fehlt die Umgebung, installiert
**Bildlaufzeit installieren** sie ohne Rootrechte in `state/image-runtime`.
Voraussetzungen: Linux, Python mit venv, Git, Internet und 25 GiB freier Speicher;
ein kompatibler NVIDIA-Treiber muss vom Systeminstaller bereitgestellt sein.
Die Installation ist abbrechbar, startet kein Modell und aktiviert die neue
Umgebung erst nach Paketprüfung. Bereits mitgelieferte Umgebungen werden erkannt;
ein Versionsupdate der Bildlaufzeit ist hier noch nicht vorgesehen.

Profile lassen sich in allen Kategorien löschen. Modell- und Komponentendateien
bleiben erhalten. Die API verhindert das Löschen des gerade ausgeführten
Bildprofils und prüft die Profilrevision gegen zwischenzeitliche Änderungen.

Neue sitzungsgeschützte API-Routen: `GET /api/v1/image-runtime`,
`POST /api/v1/image-runtime/install` und `/cancel` mit `{}` sowie
`POST /api/v1/profiles/delete` mit `{ "id": "…", "revision": 1 }`.
POST benötigt wie die übrigen Verwaltungsaktionen `X-Athena-Deck: 1`.

Das Dashboard zeigt GPU-Rechenlast und VRAM-Belegung mit separaten Balken.
Es sind Host-Gesamtwerte einschließlich anderer Dienste. Der Bild-Textencoder arbeitet auf der RTX 3060, Bildmodell und VAE auf der
RTX 5080. CPU/System-RAM bleiben für Laden und Offload beteiligt. Beide GPUs
müssen frei sein; es gibt keinen stillen CPU-Fallback. GPU-Last kann während
Vorbereitung und Laden null sein. Nach Abschluss beendet Deck den eigenen Worker und gibt dessen VRAM frei.

Unter **Entdecken** steht zusätzlich **Neu hinzugefügt** zur Verfügung. Die
Abfrage sortiert bereits auf Hugging Face nach dem Erstellungsdatum des
Repositories absteigend; sie sortiert nicht nur die beliebtesten 20 Treffer um.
Name A–Z sortiert weiterhin die angezeigte Treffermenge.

Prüfung vorhandener Studios: [Native Anwendungen und Docker](docs/NATIVE_APPLICATION_AUDIT.md).

### Optionale Docker-Anwendungen

Einstellungen → Laufzeiten → Docker zeigt Verbindung, Version und gegebenenfalls
Docker-Erstinstallation. Weitere Dienste zeigt ausschließlich Container mit
`io.athena-deck.managed=true` **und** `io.athena-deck.role=application`.
Bestehende Container werden nicht automatisch übernommen. Details zu Systemhelfer,
Installer und Grenzen: [Docker-Dienste](docs/DOCKER_SERVICES.md).

Unter Entdecken blendet **Nur Basismodelle** anhand von `base_model`,
`base_model_relation` und Hub-Tags gekennzeichnete Ableitungen aus (Finetunes,
Adapter/LoRAs, Merges und separate Quantisierungen). Es werden bis zu 100 nach
der gewählten Sortierung gelieferte Kandidaten geprüft und maximal 20 angezeigt.
Die Einstellung bleibt im Browser über Kategorien hinweg erhalten. Fehlende
Herausgeber-Metadaten können dazu führen, dass Ableitungen sichtbar bleiben;
es handelt sich nicht um eine verifizierte Liste offizieller Herausgeber.
API-Parameter: `GET /api/v1/catalog/search?...&base_only=true`.

Die Suche akzeptiert auch `owner/repository` und direkte Hugging-Face-Repository-
URLs. Eine solche Direktauswahl umgeht Kategorie- und Basismodellfilter mit einem
sichtbaren Hinweis. Bei GGUF-Dateinamen wird die Endung für die Repositorysuche
entfernt. Findet die Chat-Suche nichts, werden zusätzlich als `conversational`
gekennzeichnete GGUF-Repositories ohne `text-generation`-Tag geprüft. Das ist
keine globale Suche nach beliebigen Dateinamen im Hub.

### Hugging-Face-Zugang

Unter **Einstellungen → Zugang → Hugging Face** einen eigenen `hf_…`-Token mit Leserechten speichern, ersetzen oder entfernen. Bei freigabepflichtigen Modellen vorher auf der Modellkarte mit demselben HF-Konto Zugang beantragen. Deck akzeptiert keine Lizenzbedingungen automatisch. Siehe [HF-Zugangsrechte](https://huggingface.co/docs/hub/models-gated) und [Token](https://huggingface.co/docs/hub/security-tokens).

Der Token wird ausschließlich serverseitig unter `models/huggingface.json` im Deck-Zustandsverzeichnis gespeichert (0600, unverschlüsselt); Zustandsbackups entsprechend schützen. Er gilt für Katalogabfragen, Modell- und Komponentendownloads aller Kategorien. HTTP-Weiterleitungen auf andere Hosts erhalten keinen Authorization-Header. Entfernen verhindert neue authentifizierte Anfragen, beendet aber keinen bereits autorisierten Download. Download abbrechen bei Bedarf separat nutzen.

Interne API (nur angemeldete Administratorsitzung): `GET /api/v1/huggingface` liefert ausschließlich `{configured: boolean}`; `POST` mit `{token: "hf_…"}` speichert/ersetzt, mit `{token: null}` entfernt. POST benötigt `X-Athena-Deck: 1`. Kein API-Endpunkt liefert den gespeicherten Token zurück. HTTP 401/403 von HF ergeben Hinweise auf Token, Leserechte und Modellfreigabe; die tatsächliche Freigabe wird beim Download geprüft.

### Video: vorhandene ComfyUI-Laufzeit wiederverwenden

Video nutzt dieselbe ComfyUI-Installation wie Bildgenerierung. Es wird keine zweite Python-/CUDA-/ComfyUI-Umgebung installiert. Der gepflegte Ausführungsweg ist derzeit LTX 2.5 Distilled BF16 aus `Lightricks/LTX-2.5`; unbekannte Varianten erhalten keine automatische Freigabe.

Unter **Video → Laufzeit / Aktives Modell** prüft Deck die Bibliothek: Transformer, Textencoder, Video-VAE, Audio-VAE und Spatial-Upsampler müssen vollständig sein und aus derselben Quellversion stammen. Vorhandene Dateien werden automatisch zugeordnet. **Komponenten prüfen / nachladen** bietet fehlende Dateien an; sie landen in derselben Download-Warteschlange. Bei erfüllten Voraussetzungen erscheint **Laufzeit bereit · lädt bei Anfrage**. Das bedeutet verfügbare Dateien und Anbindung, keine Garantie gegen OOM oder einen erfolgreich geprüften Render.

**Als Videomodell aktivieren** wählt Gewichte ohne Generierungsparameter. **Übersicht → Video** beendet Decks andere GPU-Aufträge und startet einen eigenen ComfyUI-Prozess aus der gemeinsamen Installation. Die Gewichte werden erst bei einem ComfyUI-Workflow geladen. **LLM** beendet den kompletten Videoprozess und gibt dessen GPU-Speicher frei. Auch ein Deck-Neustart beendet den Deck-eigenen Prozess. Fremde Videodienste werden nur lesend geprüft und niemals von dieser Steuerung gestartet oder gestoppt.

CUDA0 ist die RTX 5080 (Diffusion und VAE); CUDA1 die RTX 3060. Der mitgelieferte Node **Deck · LTX Textencoder auf RTX 3060** weist den Encoder ausdrücklich CUDA1 zu. Frei gestaltete Workflows mit anderen Loader-Nodes können davon abweichen. Große BF16-Gewichte nutzen zusätzlich CPU-Auslagerung; Transformer und Encoder passen nicht vollständig in 16 beziehungsweise 12 GiB VRAM. ComfyUI nutzt Low-VRAM-Modus mit 1,5 GiB GPU-Reserve. Auf Athena sind etwa 47 GiB System-RAM vorhanden, der Deck-Testcontainer ist auf 32 GiB begrenzt: Ein echter Render muss hinsichtlich RAM und VRAM separat geprüft werden.

Im Videomodus stellt der gemeinsame API-Port die native ComfyUI-API und Browseroberfläche einschließlich WebSocket bereit, ohne Parameterübersetzung. Im LLM-Modus bleibt er OpenAI-kompatibel. Während eines Wechsels gilt HTTP 503. API-Clients verwenden den Deck-Bearer-Token. Die Browseroberfläche verwendet die vorhandene Deck-Anmeldung; Cross-Origin-Zugriff ist gesperrt. Der Link **ComfyUI öffnen** erscheint in der Übersicht bei laufendem Videomodus. Die bestehende LTX DeskWEB-Oberfläche erwartet die Desktop-Backend-API und ist mit diesem ComfyUI-Port nicht direkt kompatibel.

Für Zugriff auf den API-/ComfyUI-Port 8120 vom Entwicklungsrechner:

```sh
ssh -N -i /Users/mike_i386/.ssh/athena_key -o BatchMode=yes -o ExitOnForwardFailure=yes -L 8120:127.0.0.1:8120 root@192.168.1.212
```

Danach `http://127.0.0.1:8120/` im Videomodus öffnen; zunächst unter `http://127.0.0.1:8108/` anmelden. Auflösung, FPS, Dauer und Prompts werden im ComfyUI-Workflow eingestellt. Es gibt aktuell keinen automatisch vorbereiteten Video-Workflow und keinen integrierten Deck-Render-Test. Die native ComfyUI-Oberfläche bietet ihre Workflow-Templates; für die Gerätezuordnung den Deck-Textencoder-Node verwenden.

Interne Verwaltungs-API: `GET /api/v1/video` meldet Modelle, Komponenten, Blocker, Laufzeit und Prozessstatus; `POST /api/v1/video/service` mit `{id: "<Bibliotheks-ID>"}` wählt das Modell, mit `{id: ""}` hebt die Auswahl auf; `POST /api/v1/video/mode` mit `{mode: "video"}` oder `{mode: "llm"}` wechselt den GPU-Modus. Änderungen benötigen eine angemeldete Deck-Sitzung und `X-Athena-Deck: 1`. Gewichte der aktiven Auswahl bleiben gegen Bibliothekslöschung geschützt.

Für reine App-Updates kann der Debian-Installer mit `--update --reuse-runtime` die installierten Laufzeiten aus dem bisherigen Deck-Image übernehmen. Diese Option ist für App-Änderungen gedacht; gewünschte Runtime-Updates werden weiterhin ausdrücklich gebaut. Regenerierbare Video-Laufzeiten und ComfyUI-Arbeitsdaten werden bei App-Updates nicht mehr in jedes Zustandsbackup kopiert.

Optionales SwarmUI mit vorhandener ComfyUI-Laufzeit: [Installation und Betrieb](deploy/swarm-ui/README.md).

Backup und Wiederherstellung unter **Einstellungen → Backup & Restore**: [Umfang, Bedienung, API und Grenzen](BACKUP.md).

## LadyPoly YuE2

Die optionale LadyPoly-WebUI läuft als markierter Anwendungscontainer unter
Weitere Dienste und nutzt Decks Musikworker statt einer eigenen GPU-Laufzeit.
Installation, Verbindung und Einschränkungen: [LadyPoly](deploy/ladypoly/README.md).

Sprachmodell-GPUs und Vision-Projektor werden unabhängig zugeordnet. Der Modell-Split verteilt ausschließlich LLM-Gewichte; eine zusätzliche Projektor-GPU wird nur für mmproj sichtbar gemacht, nicht für Modell-Offload. Die Speicherprüfung berücksichtigt beide Geräte einschließlich Projektorbedarf.

Referenzbilder: Alle derzeit ausführbaren Bildrezepte (Qwen Image 2.1 und FLUX.2 Klein 9B) erlauben bis zu vier Bilder pro Bearbeitungsauftrag. FLUX nutzt VAEEncode und verkettete ReferenceLatent-Nodes für beide Conditioning-Zweige nach dem offiziellen ComfyUI-Workflow: https://github.com/Comfy-Org/workflow_templates/blob/main/templates/image_flux2_klein_image_edit_9b_distilled.json . Neue Modellfamilien benötigen einen passenden Workflow; hochgeladene Referenzen werden niemals stillschweigend verworfen.