hermes-arch-stack/README.md

# Hermes Arch Stack

Reproduzierbares Benutzer-Deployment für Hermes Agent auf Arch Linux mit:

- offizieller Hermes-Git-Installation unter `~/.hermes/hermes-agent`
- von Hermes erzeugtem systemd-User-Service für den Messaging Gateway
- optionalem lokalen llama.cpp/OpenAI-kompatiblen Modellendpunkt
- optionalem CPU-Kompressionsserver für Hermes
- optionalem signal-cli HTTP-Daemon
- robustem Hermes-Update mit Vorprüfung, Retry, Backup und Rollback
- regelmäßigen Healthchecks und Selbstheilungsversuchen
- Statusmeldungen an Telegram und Signal
- systemd-Timern für Updates und Zustandsprüfungen
- optionalem CUDA-Build von llama-server, llama-cli und llama-bench
- Qwen-/RTX-3080-Profilen mit prüfbarem Wechsel und Rückweg

Stand: 2026-10-12. Für deine **bestehende Workstation** zuerst
[`docs/WORKSTATION.md`](docs/WORKSTATION.md) lesen. Der Schnellstart unten ist für
eine neue Maschine. Hardware-Leistungsgewinne sind noch nicht auf deiner GPU
gemessen. Es wird kein Gitea-Server angelegt und nichts automatisch gepusht.

Das Repository enthält **keine Zugangsdaten, Signal-Sitzung oder
Modellgewichte**. Diese Daten werden lokal angelegt und sind durch `.gitignore`
ausgeschlossen.

## Schnellstart auf einer neuen Arch-Maschine

```bash
git clone ssh://git@GITEA/OWNER/hermes-arch-stack.git
cd hermes-arch-stack

./install.sh --install-packages --install-hermes
```

Für den lokalen GPU-Endpunkt anschließend den
[`CUDA-Installer`](docs/LLAMA_INSTALL.md) ausführen. Ein vorhandener Server kann
stattdessen über `LLAMA_SERVER_BIN` verwendet werden. Der Installer benötigt
funktionierende NVIDIA-Treiber; diese werden nicht von diesem Repo eingerichtet.
`--install-packages` führt ein vollständiges `pacman -Syu` aus: bei Kernel-/
Treiberänderungen einen Neustart einplanen.

Danach die beim ersten Lauf erzeugten lokalen Konfigurationen bearbeiten:

```bash
$EDITOR ~/.config/hermes-stack-maintenance/config.env
$EDITOR ~/.config/hermes-stack-maintenance/llama.env
# Bei Nutzung der lokalen Kompression:
$EDITOR ~/.config/hermes-stack-maintenance/compression.env
$EDITOR ~/.config/hermes-stack-maintenance/signal-cli.env
$EDITOR ~/.hermes/.env
```

Hermes und die Messaging-Plattformen konfigurieren:

```bash
hermes setup
hermes gateway setup
hermes gateway install --force
```

In Hermes als lokalen OpenAI-kompatiblen Endpunkt `http://127.0.0.1:8080/v1`
und als Modell-ID `qwen38-27b-local` wählen. Bestehende Hermes-Konfigurationen,
Profile, Skills und Memories werden nicht durch generische Vorgaben ersetzt.
Für Neuinstallationen diese Einstellungen interaktiv vornehmen oder die eigenen
Daten gemäß Migration sicher übernehmen. Der Alias allein setzt kein Kontextlimit.

Signal benötigt zusätzlich eine installierte/verknüpfte signal-cli-Instanz.
Nach Konfiguration kann `./scripts/install-signal-cli.sh` den vorhandenen
Signal-Updater aufrufen; siehe dessen Konfiguration und `docs/MIGRATION.md`.

Optionale Dienste erst nach ihrer Konfiguration aktivieren:

```bash
systemctl --user enable --now signal-cli.service
systemctl --user enable --now llama-qwen.service
```

Maintenance aktivieren:

```bash
systemctl --user enable --now \
  hermes-stack-hermes-update.timer \
  hermes-stack-health.timer \
  hermes-stack-signal-health.timer \
  hermes-stack-signal-update-check.timer
```

Für Start ohne interaktive Anmeldung:

```bash
sudo loginctl enable-linger "$USER"
```

Abschließend:

```bash
~/.local/libexec/hermes-stack-doctor
```

## Installationsoptionen

```text
./install.sh [Optionen]

  --install-packages  Arch-Pakete mit pacman installieren
  --install-hermes    offiziellen Hermes-Installer ausführen
  --install-llama     CUDA-Build installieren (benötigt funktionierenden Treiber)
  --llama-ref REF     expliziter llama.cpp-Tag/Commit oder bewusst master
  --enable-timers     Maintenance-Timer sofort aktivieren
  --skip-browser      Hermes ohne Browser-Automation installieren (Standard)
  --with-browser      Browser-Automation nicht überspringen
```

Ohne Optionen installiert das Skript nur die versionierten Dateien und legt
fehlende Beispielkonfigurationen an. Bestehende lokale Konfigurationen werden
nicht überschrieben.
Ersetzte Wrapper und Units werden vorher gesichert. Eine vorhandene
hermes-gateway.service wird nicht neu erzeugt. Ein Modell wird erst beim echten
Start des llama-Dienstes geladen, nicht bei der Konfigurationsprüfung.

## RTX 3080 und Qwen

```bash
~/.local/libexec/hermes-stack-llama-run --check
~/.local/libexec/hermes-stack-llama-profile list
~/.local/libexec/hermes-stack-llama-report
```

Für neue Konfigurationen ist `desktop-64k` der Standard: 64K Kontext,
4096 MiB Fit-Zielmarge, Reasoning-Budget 128 ohne Reasoning-Preserve.
Das priorisiert Spielraum für Browser und Desktop auf einer gemeinsam genutzten
GPU. Die früheren Profile bleiben für bewusste Vergleiche verfügbar.
Bestehende Konfigurationen werden nicht umgestellt. Bei expliziten `LLAMA_ARGS`
und leerem `LLAMA_PROFILE` wirken die Profile nicht.

Der optionale Dienst `llama-compression.service` verwendet eine eigene
`compression.env`, Port 8081 und CPU-Ausführung einschließlich KV-/Op-Offload.
Für beide Server werden Modellgewichte separat bereitgestellt. Einrichtung,
Messgrenzen und Migration: [`docs/RTX3080.md`](docs/RTX3080.md).

Profilwechsel ändern zunächst nur eine separate Auswahl-Datei. Ein Neustart
benötigt `hermes-stack-llama-restart --jobs-finished`. Der Healthcheck teilt das
Update-Lock und löst bei Backend-HTTP-Timeouts keine Inferenz-Neustarts mehr aus.

## Update-Verhalten

`hermes-stack-hermes-update` führt folgende Schritte aus:

1. exklusives Lock und Prüfung auf lokale Änderungen
2. `origin/main`-Fetch mit begrenzten Retries und letztem HTTP/1.1-Fallback
3. schneller Abschluss ohne Backup, wenn kein Update vorliegt
4. komprimiertes Backup vor jeder Änderung
5. Stoppen des Gateways und Aufruf von `hermes update`
6. einmaliger Retry bei eindeutig transientem Fetch-Fehler
7. Konfigurationsmigration und frischer Gateway-Neustart
8. Gateway-Healthcheck; bei Fehler Wiederherstellung des gesicherten Checkouts und der erfassten Konfigurationsdateien
9. separater llama.cpp-Healthcheck ohne unsinnigen Hermes-Rollback
10. Aufbewahrung der drei neuesten Hermes-Backups

Ein Fehler von Telegram oder Signal kann den Updateprozess niemals fehlschlagen
lassen. Detaillierte Zwischenstände landen im Journal; nur zusammengefasste
Ergebnisse werden versendet.

## Bedienung

```bash
# Update manuell
systemctl --user start hermes-stack-hermes-update.service

# Status und Logs
systemctl --user status hermes-stack-hermes-update.service
journalctl --user -u hermes-stack-hermes-update.service -n 200
journalctl --user -t hermes-stack-maintenance -n 100

# Benachrichtigung testen
~/.local/libexec/hermes-stack-notify \
  "Hermes-Stack: Benachrichtigungstest"

# signal-cli nach einer Update-Meldung aktualisieren
~/.local/libexec/hermes-stack-signal-update

# Gesamtprüfung
~/.local/libexec/hermes-stack-doctor
```

## Migration

Deployment-Code und Benutzerdaten werden bewusst getrennt behandelt. Siehe
[`docs/MIGRATION.md`](docs/MIGRATION.md) für die Übernahme von Hermes-Daten,
Signal-Sitzung und Modellgewichten.

## Gitea

Nach dem Entpacken oder Erzeugen des Repositories:

```bash
git init
git add .
git commit -m "Initial Hermes Arch deployment"
git branch -M main
git remote add origin ssh://git@GITEA/OWNER/hermes-arch-stack.git
git push -u origin main
```

Die mitgelieferte Gitea-Actions-Workflowdatei führt Syntax- und Smoke-Tests aus.
`make test` führt zusätzlich isolierte Funktionstests mit simulierten Programmen
aus. Ein echter NVIDIA-/Arch-/Signal-/Hermes-End-to-End-Test bleibt auf der
Zielmaschine erforderlich. `make archive` verwendet den letzten Commit (also
zuerst eigene Änderungen prüfen und committen).

## Grenzen der Reproduktion

Das Repo reproduziert die Deployment-Logik, nicht deine privaten Daten oder ein
eingefrorenes Arch-Abbild. Für denselben Modell-/Backendstand Quell-SHA sowie
Modell-/Projektor-Prüfsummen notieren. Der offizielle Hermes-Installer und Arch
liefern beim Neuaufsetzen sonst den dann verfügbaren Stand. Technische Quellen
stehen in `docs/LLAMA_INSTALL.md` und `docs/RTX3080.md`.

## Cleanup und dauerhafte Modellablage

Siehe [Cleanup und Wiederherstellung](docs/CLEANUP_RECOVERY.md) und
[Vorlage für lokale Modelle](config/llama-local.env.example).
Die optionalen Skripte in maintenance/ werden nicht automatisch installiert.