Anleitungen

Hermes Agent auf dem Mac mit Docker installieren

18. Mai 2026

Diese Anleitung zeigt, wie du Hermes Agent auf einem Mac mit Docker Desktop ausführst. Docker stellt die Laufzeitumgebung bereit, während die eigentlichen Hermes-Daten dauerhaft in deinem macOS-Benutzerordner bleiben.

Hermes Agent kann mit API-Schlüsseln arbeiten. Hier liegt der Schwerpunkt jedoch auf dem OpenAI Codex Provider mit ChatGPT OAuth. Die Reihenfolge ist bewusst einfach: Docker Desktop installieren, setup starten, Provider konfigurieren, Hermes Agent ausführen und anschließend das lokale Dashboard unter localhost:9119 prüfen.

Kurzüberblick

Docker Desktop muss auf dem Mac installiert und gestartet sein.
Das offizielle Image heißt nousresearch/hermes-agent.
~/.hermes wird nach /opt/data gemountet, damit Einstellungen, OAuth-Daten, Sessions, Skills und Logs erhalten bleiben.
Zuerst läuft setup, danach wird über hermes model der OpenAI Codex Provider gewählt.
Im Gateway-Betrieb mit Dashboard sollte http://localhost:9119 erreichbar sein.

Voraussetzungen

Voraussetzung	Bedeutung
Mac	Apple Silicon und Intel Macs sind möglich; wähle den passenden Docker Desktop Installer.
Docker Desktop	Führt den Hermes-Agent-Container auf macOS aus.
Terminal	Für Docker-Befehle, Setup, OAuth, Logs und Tests.
ChatGPT-Konto	Erforderlich, wenn der OpenAI Codex Provider per ChatGPT OAuth verbunden wird.
Internetverbindung	Zum Laden des Images und für den OAuth-Login.

Diagramm mit Mac, Docker Desktop, Hermes-Agent-Container und persistentem Daten-Volume — Docker führt Hermes Agent im Container aus, während `~/.hermes` die Daten auf dem Mac speichert.

Was Docker dabei übernimmt

Hermes Agent ist eine AI-Agent-Laufzeitumgebung von NousResearch. Die offizielle Dokumentation beschreibt mehrere Nutzungswege, darunter lokale Installation, Docker-Ausführung und die Nutzung als Docker terminal backend. Diese Anleitung konzentriert sich darauf, Hermes Agent selbst in einem Docker-Container auszuführen.

Der Vorteil ist eine klarere Laufzeitumgebung. Du musst Python, Node.js, Browser-Automation-Abhängigkeiten und ähnliche Werkzeuge nicht direkt in macOS installieren. Der Preis dafür ist, dass Docker Desktop zuerst laufen muss und Dateizugriff über bewusst gemountete Ordner erfolgt.

Hermes Agent nutzt im Container /opt/data als Datenpfad. Deshalb verbindet diese Anleitung den Mac-Ordner ~/.hermes mit /opt/data.

Docker Desktop installieren

Lade Docker Desktop von der offiziellen Docker-Mac-Seite. Für M1, M2, M3 oder M4 Macs nimmst du die Apple-Silicon-Version, für ältere Geräte die Intel-Version.

Der Ablauf ist einfach:

Docker Desktop von der offiziellen Mac-Installationsseite herunterladen.
Docker.dmg öffnen und Docker in den Programme-Ordner ziehen.
Docker Desktop aus Programme starten.
Erste Berechtigungs- und Hinweisfenster prüfen.
Warten, bis das Docker-Symbol in der Menüleiste stabil bereit ist.

Prüfe dann das Terminal:

docker --version

Wenn der Befehl nicht gefunden wird, läuft Docker Desktop möglicherweise noch nicht oder die CLI-Integration ist noch nicht verfügbar.

Ablauf von Docker Desktop Installation bis zur Prüfung mit docker version im Terminal — Prüfe Docker Desktop zuerst, bevor du das Hermes-Agent-Image startest.

Warum `~/.hermes` gemountet wird

Der Volume Mount ist der wichtigste Teil der Docker-Variante. Ohne ihn können Konfiguration und Authentifizierung verschwinden, sobald der Container gelöscht wird.

Nutze deshalb bei allen Hermes-Befehlen denselben Mount:

-v ~/.hermes:/opt/data

Diagramm, das den Ordner ~/.hermes auf dem Mac mit /opt/data im Docker-Container verbindet — Der Mount `~/.hermes:/opt/data` bewahrt Einstellungen, Sessions, OAuth-Daten, Skills und Logs.

Erster Start: Setup Wizard ausführen

Erstelle den Datenordner und starte den offiziellen Setup-Flow:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

--rm entfernt den temporären Container nach dem Ende. Die Daten unter /opt/data bleiben aber in ~/.hermes erhalten.

Der Setup Wizard bereitet den Datenordner vor. Je nach Version können unter anderem diese Dateien und Ordner entstehen:

Pfad	Zweck
`~/.hermes/.env`	Speichert Secrets für Provider mit API-Key, falls verwendet.
`~/.hermes/config.yaml`	Enthält Modell-, Backend-, Gateway- und Tool-Einstellungen.
`~/.hermes/SOUL.md`	Beschreibt Grundverhalten und Ausrichtung des Agents.
`~/.hermes/sessions/`	Speichert Sitzungsverläufe.
`~/.hermes/memories/`	Speichert Langzeitgedächtnis, wenn aktiviert.
`~/.hermes/skills/`	Enthält installierte Skills.
`~/.hermes/logs/`	Enthält Laufzeitlogs.

Die genauen Fragen können sich je nach Hermes-Agent-Version ändern. Für Einsteiger ist diese Orientierung hilfreich:

Setup-Frage	Praktische Wahl
Model provider	`OpenAI Codex` oder eine `Codex`-Option wählen. Wenn sie nicht sichtbar ist, Setup abschließen und später `hermes model` ausführen.
Authentication method	API-Key-Provider speichern Werte in `.env`. ChatGPT OAuth speichert Tokens in einem Auth-Speicher wie `auth.json`.
Chat system oder Gateway-Integration	Telegram, Discord oder Slack kannst du später einrichten, wenn du sie nicht sofort brauchst. Für einen dauerhaften Gateway-Betrieb kann die Einrichtung hier sinnvoll sein.
Unklare Defaults	Zuerst Defaults übernehmen und nach erfolgreicher Installation `config.yaml` anpassen.

Kurz gesagt: Lasse setup zuerst Basisdateien und Ordner erstellen. Wenn die Provider-Auswahl unklar ist, öffne sie danach erneut mit hermes model.

Prüfe danach den Ordner:

ls -la ~/.hermes

Prüfe außerdem, ob config.yaml existiert. Die ganze Datei solltest du nicht veröffentlichen; lokal reicht ein Blick auf den Anfang.

sed -n '1,80p' ~/.hermes/config.yaml

Gib .env nicht im Terminal aus und teile die Datei nicht, weil sie Secrets enthalten kann. Wenn du nur prüfen willst, ob die Datei existiert:

ls -la ~/.hermes/.env

Wenn setup endet, aber ~/.hermes/config.yaml fehlt oder der Ordner leer bleibt, prüfe zuerst den Volume Mount. Der Befehl muss -v ~/.hermes:/opt/data enthalten.

ChatGPT OAuth konfigurieren

Falls die Provider-Auswahl im Setup nicht abgeschlossen wurde, öffne den Model Picker:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent model

Wähle OpenAI Codex oder den passenden Codex-Eintrag. Wenn Hermes Agent eine URL oder einen Device Code anzeigt, öffnest du diese im Mac-Browser und meldest dich mit deinem ChatGPT-Konto an.

Einige Versionen unterstützen auch diesen direkten Credential-Befehl:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

Das OAuth-Token soll nicht nur im kurzlebigen Container liegen. Es wird im gemounteten ~/.hermes-Ordner gespeichert, zum Beispiel in einem Auth-Speicher wie auth.json. So kannst du den Container neu erstellen, ohne die Provider-Einrichtung jedes Mal zu verlieren.

Diagramm mit ChatGPT OAuth im Browser und einem Hermes-Agent-Docker-Container — ChatGPT OAuth verbindet den OpenAI Codex Provider, ohne einen OpenAI API Key direkt in den Befehl zu schreiben.

Hermes Agent ausführen

Nach Setup und Provider-Konfiguration startest du Hermes Agent interaktiv:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

Wenn die interaktive Sitzung startet, ist die Grundinstallation funktionsfähig. Nutze weiterhin denselben Volume Mount.

Die wichtigsten Optionen bedeuten:

Option	Bedeutung
`docker run`	Startet einen neuen Container.
`-it`	Öffnet eine interaktive Terminalsitzung.
`--rm`	Entfernt den temporären Container nach dem Beenden.
`-v ~/.hermes:/opt/data`	Verbindet den Mac-Ordner `~/.hermes` mit `/opt/data` im Container.
`nousresearch/hermes-agent`	Nutzt das offizielle Hermes-Agent-Docker-Image.

Dashboard unter `localhost:9119` prüfen

Wenn Setup, Provider-Konfiguration und interaktiver Start funktionieren, prüfe Image und Version:

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

Den OAuth-Status prüfst du mit demselben Datenordner:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth list

Für Gateway und Web Dashboard im Hintergrund werden beide Ports freigegeben:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Öffne danach http://localhost:9119 im Browser. Auch http://127.0.0.1:9119 sollte funktionieren. Das Dashboard dient lokal zur Verwaltung von Einstellungen, Sessions, Logs und Skills.

Wenn nichts lädt, prüfe Antwort und Logs:

curl -I http://127.0.0.1:9119

Logs zeigen Laufzeitdetails:

docker logs --tail 50 hermes

Dashboard-Zeilen können mit [dashboard] beginnen.

Stoppe und entferne den Hintergrundcontainer so:

docker stop hermes
docker rm hermes

Häufige Probleme

Problem	Prüfung
`Cannot connect to the Docker daemon`	Docker Desktop läuft noch nicht.
`docker: command not found`	Die Docker-CLI ist im Terminal nicht verfügbar.
OAuth-URL öffnet nicht	URL oder Device Code aus dem Container in den Mac-Browser kopieren.
OpenAI Codex Provider ist nicht sichtbar	Das neueste Hermes-Agent-Image ziehen und das Menü `hermes model` erneut prüfen.
Einstellungen verschwinden	Der Mount `-v ~/.hermes:/opt/data` fehlt oder ist anders.
Permission error	Prüfen, ob der aktuelle macOS-Benutzer in `~/.hermes` schreiben darf.
Dashboard öffnet nicht	`-p 9119:9119`, `-e HERMES_DASHBOARD=1` und `[dashboard]` in den Logs prüfen.
Portkonflikt	Ein anderer Prozess nutzt bereits `8642` oder `9119`.

Auf Apple-Silicon-Macs behandelt Docker Desktop Architekturunterschiede normalerweise automatisch, solange du kein Intel-only Image erzwingst. Starte mit dem offiziellen latest Image und einer aktuellen Docker-Desktop-Version.

Ablauf zur Prüfung von Docker, OAuth, Volume Mount, Logs und Dashboard — Prüfe nacheinander Docker, OAuth, Volume Mount, Logs und den Dashboard-Port.

Aktualisieren oder entfernen

Zum Aktualisieren ziehst du das neue Image und erstellst den Container neu. ~/.hermes bleibt erhalten:

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Container und Image entfernst du so:

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

Lösche ~/.hermes nur, wenn auch Einstellungen, OAuth-Tokens, Sessions, Skills und Logs weg sollen.

rm -rf ~/.hermes

Kernaussagen

Die zuverlässige Reihenfolge lautet: Docker Desktop installieren, setup ausführen, OpenAI Codex per ChatGPT OAuth verbinden, ~/.hermes nach /opt/data mounten und im Gateway-Betrieb http://localhost:9119 prüfen.