Athena-Deck/README.md

Athena Deck · Router 0.7

Eigenständige neue Oberfläche, Python-Standardbibliothek und HTML/CSS/JavaScript. Keine Installation von Python-Paketen oder Frontend-Builds nötig. Python >= 3.10.

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

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. 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 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.

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.

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.

WireGuard-Einstellungen

Das separate WireGuard-Modul 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 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 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.

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.

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.

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.

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 und Token.

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: externe Dienste statt Deck-Profile

Deck verwaltet für Video ausschließlich den aktiven Dienst, Start/Stopp und die GPU-Freigabe. Unter Video → Aktiver Videodienst einen administrativ eingerichteten Dienst wählen; unter Übersicht → Video starten. LLM beendet den Videodienst. Modellauswahl, Komponenten, Auflösung, Dauer, Prompts und Generierung erfolgen ausschließlich über dessen Original-API und Oberfläche. Heute ist LTX Desktop angebunden; weitere containerisierte Videodienste lassen sich mit derselben Dienststeuerung registrieren. Keine Übersetzung zwischen APIs.

Der Video-Bereich ist wieder Teil der KI-Werkzeuge. Generierungsparameter bleiben ausschließlich in der Video-Anwendung. Das frühere Testformular, die eigene Video-Laufzeitinstallation und /v1/videos-Generierung sind entfernt. Alte Profil- und Modelldaten bleiben auf Platte erhalten, werden jedoch nicht mehr als aktive Videoprofile angeboten. /v1/videos… liefert HTTP 410 mit Verweis auf die Original-API. Der ursprüngliche Deck-Python-Video-Worker wird nicht mehr installiert oder gestartet.

Die Steuerung erfolgt über den beschränkten Docker-Systemhelfer, ohne Docker-Socket in Deck. Root registriert Container-IDs, API-Adresse und Healthcheck in /var/lib/athena-deck-docker/video-services.json. Nur registrierte Dienste können gestartet/gestoppt werden; beliebige Docker-Aktionen sind ausgeschlossen. Siehe Videodienste.

Vor Videostart beendet Deck seine eigenen GPU-Aufträge, wartet auf Freigabe und verweigert den Start bei fremden GPU-Prozessen. Der alte Router bleibt unberührt. Im Videomodus wird der gemeinsame API-Port vollständig auf die Original-API des aktiven Videodienstes umgeschaltet. Chat/Bild/TTS/STT-Clients können diesen Port erst nach dem Rückwechsel auf LLM wieder verwenden. Beim Deck-Neustart wird ein laufender registrierter Videodienst erkannt und die GPU-Sperre wiederhergestellt; kein automatischer Dienststart und kein Abbruch externer Generierung beim bloßen Deck-Neustart.

LTX auf Athena: originale API am Host http://127.0.0.1:41955, bestehender SSH-Zugang über LTX Athena. Alternativer Tunnel vom Mac:

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

Dann API unter http://127.0.0.1:41956; Authentifizierung mit dem bestehenden LTX-Token, nicht dem Deck-Token. Keine Zugangsdaten in URLs. Der Port stellt eine API bereit, keine Browser-Studio-Oberfläche.

Gemeinsamer API-Port: Protokollwechsel

Im LLM-Modus bleibt der Deck-Endpunkt OpenAI-kompatibel. Im Videomodus werden HTTP-Pfad, Query, Methode, Inhalt, Antwortstatus und Antwortdaten unverändert an die registrierte Video-API weitergereicht. Es gibt keine Modell-/Parameterübersetzung. Beispiel auf Port 8120: POST /api/generate, GET /api/generation/progress, POST /api/generate/cancel. Kein /v1-Präfix für LTX. Während des Moduswechsels HTTP 503.

Am gemeinsamen Port gilt weiterhin der Deck-Bearer-Token. Der root-eigene Helfer setzt intern den separaten LTX-Token; er gibt ihn niemals an Deck oder den Browser zurück. Der interne LTX-Port 41955 bleibt unverändert, sodass der bisherige LTX-Athena-Zugang weiter funktioniert. HTTP GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS und Range-Header werden transportiert. Request-Bodies benötigen Content-Length (maximal 256 MiB); kein WebSocket-Transport. Die geprüfte LTX-Desktop-API verwendet für Fortschritt HTTP-Polling.

Ein separates LTX-Webfrontend gehört als Docker-Anwendung unter Weitere Dienste, nicht die Video-Laufzeit-Auswahl. Dieses Webfrontend ist noch nicht implementiert. Der vorhandene LTX-Athena-Client benötigt neben API-Zugriff weiterhin seine Dateiübertragung über SSH/SCP; ein Browser-Port muss Electron-Dateifunktionen separat ersetzen. Weiterleitung allein stellt keine neuen Datei-Upload-/Downloadrouten im LTX-Backend bereit.