Initial version of the Hermes self learning agent setup of JR IT Services.

2026-04-21 11:53:29 +02:00
commit 7f9b0e6c5f
31 changed files with 1966 additions and 0 deletions
@@ -0,0 +1,63 @@
+# Architektur
+
+## Ziele
+
+- Hermes parallel zu OpenClaw betreiben, ohne Port-, Volume- oder Netzwerk-Kollisionen.
+- Reproduzierbares Setup fuer eine Arch-Linux-Workstation.
+- Resilienter Betrieb mit Healthchecks, Restart-Policy, Backups und Update-Weg.
+- Komfortabler Workflow ueber ein einziges Wrapper-Skript.
+- Internetzugang fuer Hermes ueber die Host-Bridge `br0`.
+
+## Trennungsprinzipien
+
+### 1. Eigene Datenverzeichnisse
+
+- Hermes: `./state/hermes`
+- OpenClaw: separat, z. B. `./state/openclaw`
+
+Hermes schreibt seine komplette Identitaet, Konfiguration, Skills, Sessions und Memory in das gemountete Datenverzeichnis. Das darf nicht mit einem zweiten Hermes-Gateway geteilt werden.
+
+### 2. Eigene Host-Ports
+
+Default in diesem Repo:
+
+- Hermes API: `127.0.0.1:18642 -> 8642`
+- Hermes Dashboard: `127.0.0.1:19119 -> 9119`
+
+Die absichtlich ungewohnten Host-Ports reduzieren Kollisionen mit anderen lokalen Stacks. Dass die Bindung auf `127.0.0.1` erfolgt, ist Absicht: der LAN-Uplink laeuft separat ueber `br0`, die Bedienoberflaechen bleiben lokal.
+
+### 3. Eigene Netzrollen
+
+- `hermes_private`: internes Docker-Bridge-Netz fuer Compose-interne Kommunikation
+- `br0_uplink`: externes Docker-Macvlan-Netz auf Parent `br0`
+- `alan_agents_shared`: optionales Querverbindungsnetz fuer Hermes/OpenClaw
+
+Damit ist die Verkehrsrichtung klar getrennt:
+
+- Internet/LAN raus ueber `br0_uplink`
+- interne Service-Aufloesung ueber `hermes_private`
+- bewusste Interconnects ueber `alan_agents_shared`
+
+### 4. Eigene Compose-Projektkennung
+
+Der Standard-Projektname ist `alan`. Dadurch bleiben Container, Netzwerke und sonstige Docker-Ressourcen sauber benannt.
+
+## Resilienz
+
+- `restart: unless-stopped`
+- HTTP-Healthchecks fuer Gateway und Dashboard
+- `no-new-privileges`
+- definierte Ressourcenlimits
+- Backup- und Restore-Skripte
+- idempotentes Bootstrap fuer `.env`, Verzeichnisse und Shared-Netz
+- explizite Validierung des externen `br0`-Netzes vor dem Start
+
+## Nicht absichtlich eingebaut
+
+- kein Reverse-Proxy per Default
+- kein gemeinsamer Docker-Socket fuer Hermes und OpenClaw
+- kein wildes Mounten von `/home`
+- kein direkter Zwang, OpenClaw in denselben Compose-Stack zu ziehen
+- keine blind automatische Ermittlung deiner LAN-Parameter
+
+Das ist Absicht: weniger Seiteneffekte, weniger Sicherheitsrisiko, bessere Fehlersuche.