# 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.