Hermes-Agent-Fork

Eigener, dauerhaft gepflegter Fork von NousResearch/hermes-agent für Iris. Dieses Dokument erklärt das Update-Konzept, den Ablauf und wie du selbst — auch nach Monaten Pause — wieder sicher ein Update durchführen kannst.

Warum dieser Fork existiert

Iris bettet hermes-agent als Kern-Agent-Runtime ein, sowohl auf dem Mac (~/.hermes/hermes-agent) als auch auf dem Linux-Server (Docker-Container iris-hermes/iris-hermes-scheduled). Iris braucht dabei einige eigene Anpassungen am hermes-agent-Quellcode — Bugfixes für Probleme, die Iris kritisch treffen, und Iris-eigene Integrationsfeatures (z. B. target: server|client für Terminal-/Datei-Tools, Docker-outside-of-Docker-Pfadübersetzung).

Bisher liefen diese Anpassungen als 18 textuelle Laufzeit-Patches (linux-server/iris-server/hermes/patch_hermes.py), die bei JEDEM Container-Boot bzw. jeder Mac-Installation frisch auf einen neuen GitHub-Klon angewendet wurden. Das war fragil: ein git pull auf eine neuere hermes-agent-Version konnte einen Patch unbemerkt brechen — nur eine ✗-Zeile im Log, kein harter Fehler. Am 2026-09-05 führte genau das zu einem Totalausfall: der Patch, der verhindert, dass jeder Hermes-Job für immer auf "running" hängt, griff nach einem Upstream-Update nicht mehr, unbemerkt bis zum Live-Betrieb.

Jetzt existieren dieselben Anpassungen als echte, einzelne Git-Commits auf diesem Fork, oben auf der echten Upstream-Historie. Ein Update ist damit ein normaler, sichtbarer Git-Vorgang (Merge, ggf. mit Konflikten, die du siehst und lösen musst) statt eines stillen Text-Matchings, das unbemerkt scheitern kann.

Der Update-Zyklus im Überblick

flowchart TD
    GH["GitHub upstream<br/>NousResearch/hermes-agent"]

    subgraph LOCAL["Lokaler Fork — ~/Documents/2ndbrain/hermes/"]
        direction TB
        FETCH["1. git fetch upstream"]
        MERGE["2. git merge upstream/main<br/>Konflikte mit Patch-Commits von Hand loesen"]
        BUILD["3. uv venv (3.14) + uv pip install -e .<br/>Smoke-Test: Imports, hermes --help"]
        LIVE["4. Live-Test auf dem Mac<br/>echten Job durch den Gateway laufen lassen"]
    end

    PUSH["5. git push origin main"]
    FORGEJO["Forgejo origin<br/>iris/hermes-agent : main"]

    subgraph PROD["Produktion"]
        direction TB
        MAC["Mac-Iris<br/>~/.hermes/hermes-agent"]
        LINUX["Linux-Iris<br/>iris-hermes + iris-hermes-scheduled"]
    end

    GH -->|fetch| FETCH --> MERGE
    MERGE -->|Konflikt| MERGE
    MERGE -->|sauber gemergt| BUILD
    BUILD -->|Fehler| MERGE
    BUILD -->|ok| LIVE
    LIVE -->|haengt oder schlaegt fehl| MERGE
    LIVE -->|completed| PUSH
    PUSH --> FORGEJO
    FORGEJO -->|Iris-Server aktualisieren| MAC
    FORGEJO -->|Iris-Server aktualisieren| LINUX

Der zentrale Punkt: alles links von "5. push" passiert lokal auf deinem Rechner, unter deiner Kontrolle, bevor irgendeine Produktionsinstanz etwas davon sieht. Erst ein git push origin main macht einen neuen Stand für "Iris-Server aktualisieren" sichtbar — und das nur, weil du ihn vorher selbst gebaut und getestet hast, nicht weil ein Cron-Job oder ein Container-Boot blind git pull gegen GitHub gemacht hat.

Komponenten

Komponente	Was es ist
upstream (Remote)	https://github.com/NousResearch/hermes-agent.git — das echte Original. Nur fetch, nie push.
origin (Remote)	https://forgejo.lewerken.duckdns.org/iris/hermes-agent.git — dein Forgejo-Fork. Der einzige Stand, den Produktionsinstanzen sehen.
Lokales Arbeitsverzeichnis	~/Documents/2ndbrain/hermes/ — hier findet Merge, Build und Test statt. Kein Teil des 2ndbrain-Git-Repos (eigenes Repo, siehe CLAUDE.md).
PORTING-NOTES.md	Dokumentiert, welche der ursprünglich 18 Laufzeit-Patches wie übernommen wurden — Referenz bei Merge-Konflikten.
.fork-upstream-base	Der Commit-Hash des Merge-Base-Punkts zwischen origin/main und upstream/main (git merge-base origin/main upstream/main). Iris' "Hermes-Agent-Version"-Anzeige nutzt ihn, um über GitHubs Compare-API zu ermitteln, wie viele echte Upstream-Commits dem Fork fehlen, ohne dass die Produktivinstallation selbst einen upstream-Remote braucht. Muss nach jedem git merge upstream/main neu berechnet und mitcommittet werden (siehe CLAUDE.md).
Mac-Produktivinstanz	~/.hermes/hermes-agent — der tatsächlich von deinem Companion-Panel genutzte Hermes.
Linux-Produktivinstanzen	iris-hermes/iris-hermes-scheduled-Container auf alf@iris-server (und jedem weiteren deployten Linux-Server).
"Iris-Server aktualisieren"	Menüpunkt in Iris/IrisClient — löst POST /hermes/agent/update aus (Mac: IrisRemoteServer.swift, Linux: linux-server/iris-server/app/hermes_agent_update.py), die intern git pull gegen den jeweils konfigurierten Remote macht.

Ein Update durchführen

Alles im lokalen Arbeitsverzeichnis:

cd ~/Documents/2ndbrain/hermes

# 1. Upstream-Stand holen
git fetch upstream

# 2. In main mergen
git merge upstream/main
# Bei Konflikten: git log -p -- <datei> zeigt dir den ursprünglichen Patch-Commit und seine
# Begründung. Löse den Konflikt aus dieser Absicht heraus, nicht durch blindes "unsere/ihre
# Version nehmen". PORTING-NOTES.md hilft bei der Einordnung, welche Änderung wofür da ist.
git add <konfliktdatei>
git commit

Wenn ein Patch beim Mergen komplett verschwindet (Upstream hat die Zeilen, die er ändert, selbst entfernt/umgebaut), prüfe wie in PORTING-NOTES.mds "moot"-Fällen beschrieben: löst Upstream das ursprüngliche Problem jetzt selbst? Wenn ja, lass den Patch einfach weg und trage das in PORTING-NOTES.md nach. Wenn nein, baue die gleiche Absicht gegen die neue Code-Struktur neu — kein Commit einfach fallenlassen, ohne zu verstehen warum.

Testen

1. Smoke-Test (schnell, immer machen)

# Python 3.14 ist Pflicht: die Kern-Dependencies sind in pyproject.toml per Marker an
# >=3.14 gebunden (älter installiiert faktisch nichts ein — die Editable-Installation bleibt leer). Und der Installer muss uv sein —
# plain pip scheitert am Pillow-Pin-Konflikt mit browser-harness, den Upstream nur über
# [tool.uv] override-dependencies löst.
uv venv --python 3.14 /tmp/hermes-fork-test-venv
uv pip install --python /tmp/hermes-fork-test-venv/bin/python -e .
/tmp/hermes-fork-test-venv/bin/python -c "import gateway"   # oder welches Modul dein aktueller Patch berührt hat
/tmp/hermes-fork-test-venv/bin/hermes --help                # CLI-Entry-Point funktioniert

Regressionstests (bei jedem Sync mindestens die Fork-eigenen unter tests/ + die Upstream- Tests der Konfliktdateien; dafür zusätzlich uv pip install --python .../bin/python pytest pytest-asyncio mcp httpx2 starlette aiohttp pytest-timeout in denselben venv): ein Teil der Upstream-Suite schlägt auf diesem Mac umgebungsbedingt fehl — vor dem Einordnen immer gegen einen sauberen upstream/main-Worktree mit eigenem venv gegenprüfen (gleiche Failures = nicht die Schuld des Merges).

Reicht NICHT aus, um den kritischen "Job hängt für immer"-Fall auszuschließen — dafür braucht es einen echten Lauf gegen einen echten Gateway (nächster Abschnitt).

2. Live-Test auf dem Mac (der eigentlich aussagekräftige Test)

Testet den Fork im echten Zusammenspiel mit deinem laufenden Companion-Panel-Hermes, ohne etwas dauerhaft zu verändern — alles über Git-Branches, jederzeit reversibel.

cd ~/.hermes/hermes-agent

# Einmalig (überspringen, falls der Remote schon existiert):
git remote add fork-test /Users/alflewerken/Documents/2ndbrain/hermes

# Aktuellen Fork-Stand holen
git fetch fork-test

# Lokale Mac-spezifische Änderungen wegsichern (Shebang-Fix, ggf. von Hermes selbst
# generierte Skill-Notizen) — siehe unten "Rückbau" zum Wiederherstellen
git stash push -m "pre-fork-test"

# Auf den Fork-Stand wechseln (neuer Branch, falls noch nicht vorhanden)
git checkout -b fork-test-main fork-test/main
# ...oder falls der Branch schon existiert:
# git checkout fork-test-main && git merge fork-test/main

# Mac-lokalen Shebang wieder auf die eigene venv setzen (kommt nie aus dem Fork,
# siehe PORTING-NOTES.md "Nicht portierbar" — `hermes_hermes_cli_shebang`)

Öffne hermes (die Datei im Repo-Root) und setze die erste Zeile auf:

#!/Users/alflewerken/.hermes/hermes-agent/venv/bin/python3

# Gateway neu starten, damit er den neuen Code lädt
source venv/bin/activate
python -m hermes_cli.main gateway restart

# Bearer-Token für die lokale Gateway-API holen
grep API_SERVER_KEY ~/.hermes/.env

# Echten Testjob starten
TOKEN="<der Wert von oben>"
curl -s -X POST http://127.0.0.1:8642/v1/runs \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"input":[{"role":"user","content":"Antworte nur mit dem Wort OK."}]}'
# → liefert {"run_id": "run_...", "status": "started", ...}

# Status pollen, bis "completed" ODER "failed" (NIE dauerhaft "running")
curl -s http://127.0.0.1:8642/v1/runs/<run_id> -H "Authorization: Bearer $TOKEN"

Wichtige Stolperfalle: ~/.hermes/config.yamls model:-Block (das global konfigurierte Standard-Backend, das der Gateway für einen Lauf ohne explizite Modellangabe nutzt) kann vom Backend abweichen, das gerade in Iris' Einstellungen ("Agent LLM") ausgewählt ist — beide werden nicht immer synchron gehalten. Prüfe vor dem Test, welches Backend in Iris tatsächlich aktiv läuft ("Server läuft"-Anzeige in den Einstellungen), und stelle sicher, dass model.base_url in config.yaml dorthin zeigt — sonst schlägt der Testjob mit "Connection error" fehl, was nichts mit dem Fork zu tun hat, sondern nur mit einem falsch konfigurierten Backend. Bei mlx-vlm/LM Studio: der default-Modellname muss exakt der id aus GET <base_url>/models entsprechen (oft ein voller Dateipfad, kein Kurzname).

Ergebnis lesen: "status": "completed" mit einem "output"-Feld = Erfolg, der Job ist NICHT hängengeblieben. "status": "failed" mit einer klaren "error"-Meldung ist ebenfalls ein akzeptables Testergebnis (der Run-Lifecycle selbst funktioniert, das eigentliche Problem liegt woanders, z. B. Backend nicht erreichbar). Bleibt der Status über mehrere Minuten bei "running" hängen, obwohl das Backend nachweislich erreichbar ist — das ist der Fehlerfall, den dieser ganze Fork verhindern soll. Dann: NICHT pushen, den Merge-Commit nochmal prüfen, insbesondere ob gateway/platforms/api_server_runs.py (der SSE-Broadcast-Fix) den Merge überstanden hat.

Nach Forgejo pushen

Erst wenn Smoke-Test UND Live-Test beide grün sind:

cd ~/Documents/2ndbrain/hermes
git push origin main

Damit "Iris-Server aktualisieren" den Fork tatsächlich nutzt

✅ Vollständig umgestellt, verifiziert 2026-09-07. Die beiden /hermes/agent/update-Routen (Mac + Linux) machen nur noch einen reinen git pull origin main — kein patch_hermes.py- Reapply-Schritt mehr, die Datei selbst ist gelöscht.

• Mac: Iris/Resources/install_hermes.sh repointet ~/.hermes/hermes-agents origin auf den Forgejo-Fork und setzt hart auf dessen main zurück — sowohl VOR einem erneuten Lauf (damit der Installer-eigene interne git pull schon den Fork trifft) als auch DANACH (deckt eine frische Neuinstallation ab, die zwangsläufig erst von GitHub klont).
• Linux: linux-server/iris-server/hermes/Dockerfile macht denselben Repoint+Hard-Reset nach dem offiziellen NousResearch-Installer — jedes gebaute Image landet damit direkt auf dem gepatchten Fork-Stand.
• Beide bereits laufenden Produktivinstanzen (Mac-Lokalinstallation, alf@iris-servers iris-hermes/iris-hermes-scheduled) wurden am selben Tag manuell nachsynchronisiert (nicht nur künftige Neuinstallationen) — origin zeigt überall nachweislich auf den Fork, ein echter Regressionsjob läuft durch statt für immer auf "running" zu hängen.
• Ein erster Deploy-Versuch traf dabei kurzzeitig den ungepatchten Fork-Baseline-Stand (d8a07768c5), weil die 13 portierten Patch-Commits lokal committet, aber noch nicht nach Forgejo gepusht waren — gefixt durch git push origin main, danach alle Instanzen erneut synchronisiert. Lehre: ein lokaler Commit in diesem Arbeitsverzeichnis ist erst wirksam, sobald er tatsächlich git push origin main durchlaufen hat, nicht schon beim Committen.

Rückbau / Notausstieg (Mac-Live-Test)

Falls der Live-Test schiefgeht oder du zurück auf den bekannten guten Stand willst:

cd ~/.hermes/hermes-agent
git checkout main                    # zurück auf den ursprünglichen, unveränderten Stand
git stash pop                        # lokale Mac-Änderungen (Shebang etc.) wiederherstellen
source venv/bin/activate
python -m hermes_cli.main gateway restart

git remote remove fork-test und git branch -D fork-test-main räumen den Test-Remote/-Branch komplett weg, falls gewünscht — nicht nötig, beide sind harmlos, wenn sie einfach liegen bleiben.

Offene Punkte

• Upstream-Stand: Dieser Fork-Zustand enthält den 2026-11-05er Re-Sync (davor der von 2026-10-22, dessen Verlauf in PORTING-NOTES.md steht) — ab diesem Merge ist der Fork nicht mehr hinter NousResearch/hermes-agent zurück. Der Abstand wächst neu, sobald Upstream weiterentwickelt, und der nächste Re-Sync wird mit jedem weiteren Upstream-Commit teurer; Iris zeigt ihn live an (.fork-upstream-base + GitHubs Compare-API, ohne vollen git fetch upstream).
• Nach jedem künftigen git merge upstream/main nicht vergessen, .fork-upstream-base neu zu berechnen und mitzucommitten (siehe dessen Eintrag oben) — sonst zeigt die Commits-Behind-Zahl in der GUI einen veralteten, zu hohen Wert weiter an.