Athena-Deck/DEVELOPMENT.md

Entwicklung auf Athena (Debian)

Zielsystem: Debian 13, RTX 5080 und RTX 3060. Der Arbeitsplatz dient nur als Editor/SSH-Client und Browser. Die Anwendung und ihre Tests laufen auf Athena.

• Quellcode: /opt/athena-deck-dev/source
• Eigener Container: athena-deck-dev
• Zustand und Installationsmanifest: /opt/athena-deck-dev/runtime
• Serverbindung: ausschließlich 127.0.0.1:8108
• GPU-Zugriff: NVIDIA compute,utility für Telemetrie und Fit-Prüfung; keine Modellstarts.

Vom Arbeitsplatz:

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

Browser: http://127.0.0.1:8108 . Die Adresse führt durch den Tunnel zum Server. Beim ersten Öffnen neue Zugangsdaten einrichten. Vorhandene Zugangsdaten werden nicht vom Arbeitsplatz übertragen. Browser-Profilentwürfe bleiben bei gleicher Adresse erhalten. Nur diese isolierte Entwicklungsinstanz erlaubt die einmalige Browser-Einrichtung über den SSH-Tunnel (development_setup im Manifest). Der normale Debian-Installer provisioniert weiterhin vor dem Start.

Auf Athena:

cd /opt/athena-deck-dev/source
./install.sh --status --directory /opt/athena-deck-dev/runtime
./install.sh --stop --directory /opt/athena-deck-dev/runtime
./install.sh --start --directory /opt/athena-deck-dev/runtime
# Nach gezielter Aktualisierung der Quelldateien:
./install.sh --update --directory /opt/athena-deck-dev/runtime
python3 -m unittest discover -s . -v

Diese Befehle verwalten ausschließlich den eigenen, per Label geprüften Deck-Container. Produktiver Router, Modelle, WireGuard und Hostkonfiguration werden nicht verändert. Kein Docker-Socket im Webcontainer.

Profile und llama.cpp-Build/Update sind weiterhin GUI-Entwürfe. Die Netzwerk-Erweiterung ist in dieser Installation deaktiviert. Das Verschieben der Entwicklung aktiviert keine dieser Funktionen automatisch.

Verbindliche Zielarchitektur

Das Produkt wird ein nativer Debian-systemd-Dienst unter eingeschränktem Benutzer. Docker ist ausschließlich die vorläufige Testverpackung. Katalog, Downloads und spätere Worker-Adapter dürfen Docker nicht voraussetzen. Kein Docker-Socket und keine Hostprozesssteuerung über Docker. Der vorhandene WireGuard-Container bleibt unverändert; Zugriff derzeit über SSH-Tunnel.

Live-Funktionen ab 0.5

Hugging-Face-Suche nach Bereich, feste Repository-Revision, Dateiauswahl und serieller Download öffentlicher GGUF-/Safetensors-/JSON-Dateien. Eigener Ordner runtime/state/models; Fortschritt, Abbruch, 10 GiB Speicherreserve, Größenprüfung und bei vorhandenem LFS-Prüfwert SHA-256-Abgleich. Bei Neustart wird ein laufender Download nicht fortgesetzt; unvollständige Dateien sind keine Bibliothekseinträge. Keine automatische Ausführung heruntergeladener Dateien. Gated/private Modelle, Paketauflösung, VRAM-/Kontextprognose und Worker-Starts fehlen noch.

Interne API (nur angemeldeter Administrator):

• GET /api/v1/catalog/search?q=...&kind=chat|image|audio|video
• GET /api/v1/catalog/files?repo=owner/name
• GET /api/v1/catalog: Bibliothek, Downloadstatus, freier Speicher
• POST /api/v1/catalog/download: repo, filename, revision, kind
• POST /api/v1/catalog/cancel: leeres JSON-Objekt

Anbieter-Dokumentation: https://huggingface.co/docs/hub/api . Audio-Suche filtert zunächst Sprachausgabe; weitere Audioaufgaben folgen. Einzelne Dateien stellen noch keine vollständige Installation eines mehrteiligen Modells dar.

Update-Sicherungen enthalten den Konfigurationszustand, nicht die heruntergeladenen Modelldateien. Diese bleiben im persistenten Zustandsverzeichnis erhalten.

Native Laufzeitverwaltung

runtime.py verwendet ausschließlich native Prozesse (git, cmake, llama-server), keine Docker-API. Die Testverpackung enthält CUDA 12.8.1 und Build-Werkzeuge; Debian-Host und Treiber werden nicht verändert. Build-Last ist auf 2 CPUs, 8 GiB RAM und maximal zwei Compiler-Jobs begrenzt. Builds liegen unter state/runtime, werden nicht in Konfigurations-Backups dupliziert und bleiben bei Updates erhalten. Geprüfte Versionen können als Standard ausgewählt und zurückgeschaltet werden; das startet kein Modell.

GET /api/v1/runtime, /prerequisites, /releases, /log; POST /build (revision, backend, jobs), /cancel ({}), /activate (build_id), /rollback ({}), jeweils unter /api/v1/runtime. Nur Administratorsitzungen sind zugelassen. Release-Quellen: https://github.com/ggml-org/llama.cpp/releases .

Die feste VRAM-Reserve entfällt. Die Buildprüfung ermittelt die tatsächliche Unterstützung von --fit; modellbezogene Layer-/Kontextprognose wird über das unten beschriebene Fit-Werkzeug bereitgestellt. Modellstarts sind noch nicht angebunden. Keine erfundenen Schätzungen, keine absichtlichen OOM-Versuche und keine Eingriffe in produktive Worker.

Auto-Einpassung mit den bisherigen Routermodellen

llama-fit-params wird mitgebaut. GET /api/v1/runtime/references liefert die am 28.09.2026 aus dem alten Router gelesenen Profile Fast/Medium/Large/Ultra/ Uncensored. POST /api/v1/runtime/fit nimmt profile, context und slots entgegen. Die drei GGUF-Dateien werden einzeln und nur lesend in den Testcontainer eingebunden (reference_models im Entwicklungsmanifest). Keine Kopie der Gewichte, kein Zugriff auf Prompts oder Anwendungslogs.

Das offizielle Fit-Werkzeug verwendet no_alloc für Modellgewichte und liefert eine Prognose anhand des aktuellen freien Speichers, q4_0-KV-Cache und explizitem Kontext/Slots. Die automatische Reserve beträgt als Sicherheitsregel 5 % des jeweiligen Gesamt-VRAM, mindestens 512 MiB. Karten mit weniger als 10 % freiem VRAM (mindestens 1 GiB) werden vor CUDA-Initialisierung aus der Prüfung ausgeschlossen. Diese Regeln sind Sicherheitsmargen, keine gemessene exakte Modellkapazität. Es findet kein OOM-Stresstest und kein Modellstart statt. Eine Prognose ist keine Garantie unter wechselnder Parallelbelegung. Der native Betrieb kann dieselben Dateien über DECK_REFERENCE_MODELS bereitstellen.

Fit-Adapter: Das Upstream-Fit-CLI bietet die Serveroption --kv-unified nicht an. Deck setzt deshalb beim Build in tools/fit-params/fit-params.cpp vor der Backend-Initialisierung explizit params.kv_unified = true, entsprechend den bestehenden Profilen. Die Anpassung ist als shared-kv-pool-v1 im Buildstand vermerkt; die eigentliche Fit-Berechnung bleibt upstream. Fehlt der erwartete Quellanker, bricht der Build ab, statt eine andere Semantik zu verwenden.

Die Fit-Prognose gilt zunächst für das Textmodell. Vision-Projektoren und MTP der bisherigen Routerprofile sind nicht eingerechnet. Außerdem ersetzt sie keine RAM-/Lastprüfung eines späteren Worker-Starts im begrenzten Testcontainer.

Verifikation: CUDA-Release b11229 (c2a9e1606807970f4ee3167bacd951699c89caea) für 86/120 erfolgreich gebaut. Medium, 160000 Kontext, zwei Slots: echte Fit-Prognose erfolgreich. Bei damaliger Parallelbelegung 0 GPU-Modelllayer; GPU-Rechenpuffer 1044 MiB, Host Modell 13635 MiB, Kontext 3111 MiB, Compute 93 MiB. Das überschreitet das 8-GiB-RAM-Limit der Testinstanz und wird als nicht startbar markiert. Keine Modellgewichte allokiert, alle zuvor vorhandenen Container-Startzeiten unverändert. 46 Tests erfolgreich.

Der verifizierte Erstbuild liegt in state/runtime-verification; state/runtime/<Build-ID> verweist intern darauf, damit seine Build-RPATHs erhalten bleiben. Beide Verzeichnisse gehören ausschließlich Deck und bleiben bei Updates bestehen. Künftige Builds entstehen direkt unter state/runtime.