# Athena Deck · Prototyp 0.4 Eigenständige neue Oberfläche, Python-Standardbibliothek und HTML/CSS/JavaScript. Keine Installation von Python-Paketen oder Frontend-Builds nötig. Python >= 3.10. ## 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. Andere Modellstarts sind noch nicht angebunden. Details: [Modellverwaltung](STUDIO.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, Demo-Prozess 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. Modelllaufzeiten sind noch nicht 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 Demo-Prozess lädt kein Modell. ## Interne API v1 Alle Antworten JSON. Zugangsdaten werden geschützt persistiert; Demo-Zustand ist flüchtig. GUI verwendet nur diese API. | Methode | Pfad | Ergebnis | |---|---|---| | GET | `/api/v1/status` | Name, Version, Laufzeit, Modus, Demo-Zustand | | GET | `/api/v1/hardware` | Verfügbarkeit, Messzeit, CPU, RAM, GPU-Liste, Fehler | | GET | `/api/v1/demo` | state, reachable, pid, port, location | | POST | `/api/v1/demo/start` | Idempotent starten und Health prüfen | | POST | `/api/v1/demo/stop` | Idempotent eigenen Kindprozess stoppen | Browser-POST benötigt Sitzung und `X-Athena-Deck: 1`; Browser-Origin muss zum Host passen. API-Clients verwenden für freigegebene Dienst-Endpunkte den separaten Bearer-Token. Host-Allowlist: localhost oder 127.0.0.1 mit tatsächlichem UI-Port. Keine CORS-Freigabe. 403 bei ungültigem Zugriff, 404 bei unbekannten Pfaden, 503 bei fehlgeschlagener Demo-Bereitschaft. Keine frei übergebbaren Befehle, Prozess-IDs, Service-Namen oder Remote-Ziele. ```sh curl -H 'Authorization: Bearer ' http://127.0.0.1:8108/api/v1/status curl -X POST -H 'Authorization: Bearer ' http://127.0.0.1:8108/api/v1/demo/start curl -X POST -H 'Authorization: Bearer ' http://127.0.0.1:8108/api/v1/demo/stop ``` 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 bedarfsgesteuert mit fünf Sekunden Cache, GUI-Polling alle fünf Sekunden. Keine Historie und kein Hintergrund-Collector bei geschlossener Hardware-Seite. ## Struktur und Grenzen - `server.py`: API, separater HardwareProvider, eigenständiger DemoService. - `demo.py`: Health-only HTTP-Kindprozess auf dem Debian-Server, ohne Modellabhängigkeiten. - `collect_hardware.py`: fest begrenzte lesende Linux-Hardware-Abfragen. - `index.html`, `app.js`, `style.css`: neue responsive Oberfläche. - `test_server.py`: Prozess-Lebenszyklus, Kontrollgrenzen, Hardware-Ausfall. Sprachmodelle/Chat, Bildgenerierung, Audio und Video besitzen jetzt eine gemeinsame Modellverwaltung; Weitere Dienste bleibt Platzhalter. Downloads und Profile sind aktiv, Chats und Modellwechsel noch nicht. Spätere Modellprofile und native llama.cpp-Worker sollten eigene Service-Adapter mit derselben Status-/Start-/Stopp-Trennung erhalten. Noch kein Worker-Registry, Scheduler oder produktionsreifer Worker-Supervisor. Die optionale Server-Instanz hat eine eigene Passwortanmeldung; ihre Netzwerkgrenzen stehen in der Modul-Dokumentation. SIGKILL/Absturz-Cleanup ist nicht implementiert; regulär Ctrl+C/SIGTERM verwenden. Der Hardware-Collector ändert keine Host-Konfiguration. Die optionale Netzwerkmodul-Installation erzeugt einen eigenen Docker-Container samt Portbindungen. ## 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`. Die Hardware-Seite 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`.