Hermes Agent auf einem VPS hinter WireGuard

Anleitung: Hermes Agent in Docker auf dem VPS yaksha, Dashboard hinter Caddy und nur per WireGuard erreichbar, Container vom Tunnel-Netz abgeschottet.

Artikel Erstellt Aktualisiert Auch auf Englisch: Hermes Agent on a VPS Behind WireGuard

Geprüft von adrian am

Hermes Agent läuft in Docker auf dem VPS yaksha. Das Dashboard liegt unter https://sandbox.altner.cloud/hermes-agent/ und ist nur über den WireGuard-Tunnel erreichbar. Öffentlich wird es erst später, und nur nach meiner Freigabe.1

Stand

Läuft seit dem 13.11.2026 mit Version v0.23.1. Das Modell ist anthropic/claude-haiku-5.5 über OpenRouter, die Websuche nutzt Exa (kostenloser Tarif), TTS läuft über Piper. Die Spracheingabe ist abgeschaltet.

1. Container

Grundlage ist die offizielle Docker-Anleitung.2 Alles liegt in /srv/altner.cloud/sandbox/hermes-agent mit compose.yaml, .env (chmod 600) und data/.

  • Image: nousresearch/hermes-agent:v0.23.1. Die Tags haben ein v; 0.23.1 gibt „manifest unknown“.
  • Befehl: gateway run mit HERMES_DASHBOARD=1, PUID/PGID 1000 (der Host-Nutzer, dem data/ gehört).
  • Login: HERMES_DASHBOARD_BASIC_AUTH_USERNAME, …_PASSWORD und …_SECRET (mindestens 32 zufällige Bytes) aus der .env.
  • Präfix: HERMES_DASHBOARD_PUBLIC_URL: https://sandbox.altner.cloud/hermes-agent.
  • Port: 127.0.0.1:8100:9119. Das Dashboard ist nur über Caddy erreichbar, die Gateway-API (8642) bleibt im Container.
  • Daten: ./data:/opt/data, dazu shm_size: 1g für die Browser-Werkzeuge und Grenzen von 3 GB RAM und 2 CPUs.
  • Netz: festes Subnetz 172.31.0.0/24 mit Gateway 172.31.0.1. Über docker-proxy sieht das Dashboard dieses Gateway als Absender, deshalb steht in data/config.yaml dashboard.trusted_proxies: ["172.31.0.1"].

Modell und Werkzeuge stellt man mit docker exec -it hermes hermes setup ein. Der Assistent schreibt die API-Schlüssel nach data/.env, nicht in die .env von Compose. hermes doctor prüft das Ergebnis; Warnungen zu Bildgenerierung, Computer Use oder „install out of sync“ waren harmlos.

2. Caddy

Eine Site-Datei in /etc/caddy/sites/, geladen mit caddy reload --config /etc/caddy/Caddyfile:

@outside not remote_ip 10.0.0.0/24

handle /hermes-agent {
    route {
        abort @outside
        redir * /hermes-agent/ permanent
    }
}

handle_path /hermes-agent/* {
    route {
        abort @outside
        reverse_proxy 127.0.0.1:8100 {
            header_up X-Forwarded-Prefix /hermes-agent
        }
    }
}

@hermes_static path /assets/* /fonts/* /fonts-terminal/* /ds-assets/*
handle @hermes_static { … gleiche route … }
  • abort im Handler: Auf Site-Ebene läuft abort in Caddys Direktiven-Reihenfolge erst nach handle/handle_path und greift dort nie. Kurzzeitig war die Login-Seite deshalb öffentlich.
  • redir *: redir /hermes-agent/ permanent liest den Pfad als Matcher und liefert ein leeres 200.
  • Statische Pfade: In v0.23.1 schreibt das Dashboard nur index.html auf das Präfix um. Nachgeladene Teile kommen ohne Präfix von /assets/, deshalb blieb die Chat-Seite leer. Den Block @hermes_static entfernen, sobald Hermes das behebt.
  • Kein encode: Chat-Stream und WebSockets (/api/ws, /api/pty) dürfen nicht gepuffert werden.
  • Access-Log: mode 0644 setzen, sonst kann der Deploy-Nutzer es nicht lesen.

3. Zugang über WireGuard

Der Tunnel des Macs ist ein Split-Tunnel (AllowedIPs = 10.0.0.0/24), deshalb schickt DNS die Domain zu Cloudflare. Das ergab erst einen Cloudflare-Fehler 520, später „Sign-in failed“.1

  1. In /etc/hosts auf dem Mac: 10.0.0.1 sandbox.altner.cloud und ::ffff:10.0.0.1 sandbox.altner.cloud. Die zweite Zeile fängt IPv6 ab.
  2. In Cloudflare bekommt sandbox eigene A/AAAA-Einträge auf DNS only. Ein Name hinter dem Proxy veröffentlicht einen HTTPS/SVCB-Eintrag mit IP-Hinweisen; Safari folgt ihnen und ignoriert /etc/hosts. Der Wildcard-Eintrag *.altner.cloud bleibt hinter dem Proxy.

4. Nutzung

  • Desktop-App: Verbindungsart Remote gateway, URL https://sandbox.altner.cloud/hermes-agent, mit dem Dashboard-Login anmelden, dann Test.3 Connect via SSH erwartet eine normale Installation und geht mit Docker nicht; Local gateway würde ein zweites Hermes auf dem Mac starten.
  • Einfügen in Safari: Der Chat fängt Cmd+V ab und fragt nach Zugriff auf die Zwischenablage, den Safari verweigert. Stattdessen mit Rechtsklick einfügen oder Chrome nutzen.
  • Chats löschen: im Dashboard unter Sessions oder mit docker exec hermes hermes sessions delete --yes <id>.
  • Kosten: Haiku 5.5 kostet bis 100.000 Prompt-Tokens 0,10 $ pro Million Eingabe- und 0,50 $ pro Million Ausgabe-Tokens, darüber das Fünffache. Cache-Lesen kostet 0,01 $.

5. Spracheingabe

  1. docker exec -u hermes hermes hermes pm install pnpm. Ohne das bricht der nächste Schritt mit „tools not on PATH“ ab.
  2. docker exec -u hermes hermes hermes pm install --extra stt-whisper, danach docker compose restart. Das Paket liegt dann in data/installs.
  3. In config.yaml stt.local.model: small und stt.language: de setzen.

Auf 4 CPU-Kernen ohne GPU brauchte jede Aufnahme etwa 5 Sekunden, der Text war schlecht, und der VAD-Filter schnitt bei manchen Aufnahmen bis zu 80 % weg. Die Spracheingabe ist deshalb aus (stt.enabled: false), das spart etwa 500 MB RAM. Der Weg zurück wäre ein Groq-API-Schlüssel (whisper-large-v3-turbo).1

6. Abschottung

Der Container sieht nur data/, läuft nicht privilegiert und hat keinen Docker-Socket. Dienste des Hosts auf 127.0.0.1 sind nicht erreichbar. Über das Netz erreichte er aber den Mac durch den Tunnel (AirPlay auf 5000/7000, Syncthing auf 22000). Eine Regel in Dockers Kette DOCKER-USER schließt das:1

iptables -I DOCKER-USER 1 -s 172.31.0.0/24 -d 10.0.0.0/24 \
  -m conntrack --ctstate NEW,INVALID -m comment --comment hermes-wg-block \
  -j REJECT --reject-with icmp-admin-prohibited
  • Dauerhaft: /usr/local/sbin/hermes-wg-block.sh setzt die Regel idempotent. Die systemd-Unit hermes-wg-block.service startet es mit After=/Requires=/PartOf=docker.service und WantedBy=docker.service, so kommt die Regel nach jedem Neustart von Docker oder Server zurück.
  • Nicht /etc/nftables.conf: Die Datei beginnt mit flush ruleset. Den nftables-Dienst zu starten würde alle Docker-Regeln löschen.
  • Getestet: Die Ports des Macs geben jetzt „no route to host“, Internet, OpenRouter und Dashboard funktionieren weiter. Die Desktop-App ist nicht betroffen, weil ihre Verbindungen bei Caddy auf dem Host enden.
  • Rückgängig: sudo systemctl disable --now hermes-wg-block.

Vor einer öffentlichen Freigabe

  • Alle Zeilen abort @outside entfernen.
  • Die hosts-Einträge auf dem Mac entfernen.
  • Zusätzliche Anmeldung davor erwägen, etwa Caddy Basic Auth oder OIDC.

Nur mit meiner Freigabe.

Beruht auf

Mehr dazu

Thema

  • KI-Agenten KI-Apps, deren Sprachmodell Werkzeuge aufruft, um Arbeit zu erledigen, etwa Claude Code und Claude Desktop, und wie du sie sicher betreibst.

Nutzt

  • Hermes Agent Open-Source-KI-Agent von Nous Research mit Web-Dashboard, Desktop-App, Werkzeugen, Skills und Gedächtnis. Läuft auf dem eigenen Server, etwa in Docker.

Siehe auch

In der Graph-Ansicht zeigen