alan/README.md

alan-agents-workstation

Docker-Setup fuer eine Arch-Linux-Workstation, damit Hermes Agent parallel zu OpenClaw laufen kann, ohne sich in die Quere zu kommen.

Wichtige Netzannahme in diesem Repo:

• Internetzugang fuer Hermes laeuft ueber dein br0.
• Dafuer haengt Hermes an einem externen Docker-Macvlan-Netz, das auf dem Host-Bridge-Interface br0 basiert.
• OpenClaw bleibt ein separater Stack mit eigenen Ports, Volumes und idealerweise demselben Uplink-Prinzip.

Der Fokus liegt auf:

• saubere Trennung von Ports, Volumes und Netzwerken
• resilientes Compose-Setup
• komfortabler Workflow ueber alanctl
• einfache Ablage in einem Gitea-Repo
• explizite Beruecksichtigung von br0

Was dieses Repo liefert

• compose.yaml fuer Hermes Gateway und optionales Dashboard
• Wrapper-Skript scripts/alanctl
• Backup/Restore/Update/Rollback-Workflow
• Doku fuer Architektur, br0, Betrieb und Gitea-Import
• systemd-User-Unit als Vorlage
• Beispiel fuer getrennte OpenClaw-Integration

Schnellstart

cp .env.example .env
# .env an dein LAN anpassen: BR0_SUBNET, BR0_GATEWAY, BR0_IP_RANGE
./scripts/alanctl bootstrap
./scripts/alanctl net-create-br0
./scripts/alanctl init-hermes
./scripts/alanctl up

Optional mit Dashboard:

./scripts/alanctl up --dashboard

Danach:

• Hermes Health/API lokal: http://127.0.0.1:18642/health
• Hermes Dashboard lokal: http://127.0.0.1:19119

Langfristige Repo-Pflege in Gitea

Neu fuer den laufenden Betrieb:

• CHANGELOG.md fuer nachvollziehbare Aenderungen
• CONTRIBUTING.md fuer Arbeitsregeln
• docs/release-process.md fuer Tags und Release Notes
• docs/release-template.md als kopierbare Vorlage fuer Gitea-Releases
• docs/upgrade-policy.md fuer Upgrade-Klassen und Rollback-Regeln
• docs/maintenance.md fuer wiederkehrende Pflege
• .gitea/ISSUE_TEMPLATE/* und .gitea/pull_request_template.md
• .gitea/workflows/repo-check.yml fuer einfache Repo-Pruefungen
• scripts/release-check und scripts/new-release
• .editorconfig fuer konsistente Formatierung
• CODEOWNERS und docs/maintainers.md fuer Review-Zustaendigkeiten

Release-Vorbereitung:

./scripts/release-check
./scripts/new-release 0.1.1

Warum zwei Netzebenen?

• br0_uplink: externer Uplink fuer Internet/LAN via br0
• hermes_private: internes Compose-Netz fuer saubere Service-Kommunikation
• alan_agents_shared: optionales Querverbindungsnetz nur bei echtem Bedarf

So bekommt Hermes den Internetzugang ueber br0, waehrend API und Dashboard lokal auf 127.0.0.1 gebunden bleiben.

Workflow

Status

./scripts/alanctl status

Logs

./scripts/alanctl logs
./scripts/alanctl logs dashboard

Health / Diagnose

./scripts/alanctl doctor

Backup

./scripts/alanctl backup

Restore

./scripts/alanctl restore ./backups/hermes/hermes-YYYYMMDD-HHMMSS.tar.gz

Update

Empfohlen: Hermes nicht auf latest lassen, sondern auf einen bewusst gesetzten Tag pinnen.

./scripts/alanctl pin-hermes stable
./scripts/alanctl update-hermes           # aktualisiert auf den aktuell gepinnten Tag
./scripts/alanctl update-hermes v0.9.3    # gezieltes Upgrade auf einen bestimmten Tag

Rollback bei Bedarf:

./scripts/alanctl rollback-hermes

Arch-Linux-Hinweise

Installiere mindestens:

sudo pacman -S docker docker-compose curl iproute2
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
newgrp docker

Fuer den optionalen Host-Shim brauchst du sudo fuer ip link und ip route.

Wichtige Macvlan-Einschraenkung

Bei Docker-Macvlan koennen Host und Container nicht direkt miteinander sprechen, solange du keinen Host-Shim anlegst.

Wenn du das brauchst, z. B. fuer lokale Tests vom Host auf die br0-IP des Containers:

./scripts/alanctl net-create-shim

Details dazu stehen in docs/bridge-br0.md.

Verzeichnisstruktur

.
├── compose
│   └── openclaw.override.example.yaml
├── compose.yaml
├── docs
│   ├── architecture.md
│   ├── bridge-br0.md
│   ├── gitea-import.md
│   ├── hermes.md
│   ├── maintenance.md
│   ├── openclaw-coexistence.md
│   ├── release-process.md
│   └── upgrade-policy.md
├── scripts
│   ├── alanctl
│   ├── new-release
│   └── release-check
├── state
│   └── hermes/
├── backups
│   └── hermes/
└── systemd
    └── user
        └── alan-hermes.service

Warum die Ports absichtlich ungewoehnlich sind

Die offiziellen Hermes-Beispiele verwenden hostseitig meist 8642 fuer die API und 9119 fuer das Dashboard. Dieses Repo mappt absichtlich auf 18642 und 19119, bindet sie aber nur an 127.0.0.1, damit ein bestehendes OpenClaw- oder sonstiges Dev-Setup auf der Workstation seltener kollidiert.

Maintainer und Review

• .editorconfig sorgt fuer konsistente Grundformatierung in Editor und CI
• CODEOWNERS beschreibt Default-Owner und Review-Schwerpunkte
• docs/maintainers.md ist die betriebliche Fallback-Doku, falls deine Gitea-Instanz CODEOWNERS nicht automatisch auswertet

Lizenz und Security

• LICENSE: MIT-Lizenz fuer klare Weitergabe und Anpassung
• SECURITY.md: Richtlinie fuer Security-Meldungen und gepflegte Staende

Sicherheit und Betriebsgrenzen

• Dieses Repo trennt Hermes und OpenClaw bewusst.
• Nutze das Shared-Netz nur, wenn wirklich noetig.
• Lege keine Secrets ins Git-Repo.
• Wenn du OpenClaw separat betreibst, gib ihm andere Host-Ports und eigene Volumes.
• Das br0-Uplink-Netz ist extern und wird absichtlich nicht blind bei docker compose up erzeugt.

Naechster sinnvoller Ausbau

• Reverse-Proxy mit lokalem DNS-Namen
• systemd-User-Integration aktivieren
• Borg/Restic fuer Off-Host-Backups
• eigene Profiles fuer mehrere Hermes-Instanzen
• optional identisches br0-Uplink-Muster fuer OpenClaw

Update-Strategie

Dieses Repo ist bewusst so gebaut, dass Updates kontrolliert ablaufen:

• HERMES_TAG wird in .env gepinnt
• update-hermes erstellt zuerst ein Backup
• danach wird das Ziel-Image gepullt und Hermes neu erstellt
• der Healthcheck wird aktiv abgewartet
• bei Fehlschlag wird automatisch auf den vorherigen Tag zurueckgestellt
• der zuletzt erfolgreiche Stand wird in state/hermes/.last-known-good.env gespeichert

Fuer reproduzierbare Setups auf Workstation oder Homeserver ist das deutlich robuster als blindes Arbeiten mit latest.