2026 Hermes Agent: Vollständiger Installations- und Konfigurationsleitfaden — Schritt-für-Schritt-Praxis von null bis zum Lauf

2. Wo die meisten Anleitungen aufhören

1. Die Decke: „Start erfolgreich“. Ein Willkommensbanner im Terminal bedeutet nicht, dass das Modell erreichbar ist, Datei-Tools funktionieren oder ein Gateway Nachrichten empfängt. Hermes ist erst wirklich nutzbar nach Umgebungsprüfung, Modellverbindung, Berechtigungsgrenzen, nachvollziehbaren Logs und Abnahme eines Praxisbeispiels mit geringem Risiko.
2. Versteckte Kosten: Keys und Pfade überall verstreut. API-Keys nur in Notizen; config.yaml und .env widersprechen sich; der Workspace zeigt auf das gesamte Home — ein Fehlgriff kann SSH-Keys oder ein Produktions-Repo überschreiben.
3. Stabilität & Audit: installieren und vergessen, wo Logs liegen. Bei Fehlern löscht blindes Neuinstallieren die einzigen Hinweise in ~/.hermes/logs/errors.log; ohne Backup können Sie Config nach einem Upgrade nicht zurückrollen.

3. Vorbereitung vor der Installation: Mac- & Umgebungs-Checkliste

Ziel: Netzwerk-, Git- oder Speicherprobleme nicht mitten in der Installation entdecken. Abnahmekriterium: alle Punkte unten abgehakt, bevor Sie das Install-Script starten.

• System: macOS 12+ (Intel oder Apple Silicon; Apple Silicon bietet mehr Optionen für lokale Inferenz, Cloud-Modelle folgen weiterhin der Provider-Doku).
• Git: beim offiziellen Git-Installer ist Git die einzige harte Voraussetzung (git --version ≥ 2.30 empfohlen). Ohne Git: Xcode Command Line Tools oder brew install git.
• Netzwerk: GitHub raw (Install-Script) und die API Ihres LLM-Providers müssen erreichbar sein; in Firmennetzen HTTPS_PROXY früh setzen.
• Speicher: der Installer lädt Python 3.11, Node.js v22, ripgrep, ffmpeg und das Repo — ≥ 2 GB frei reservieren (mit Skills-Cache eher 1,5–3 GB; aktuelle Doku beachten).
• Berechtigungen: Benutzerinstallation braucht kein sudo; bei früherer Root-Installation können Daten unter /root/.hermes liegen, nicht unter den hier genannten Pfaden.
• Backup: existiert bereits ~/.hermes, zuerst cp -a ~/.hermes ~/.hermes.bak-$(date +%F).
• Testverzeichnis: isolierten Workspace anlegen (wir nutzen durchgängig ~/hermes-lab). Nicht als erstes Beispiel ~/Documents, Produktions-Git-Repos oder Verzeichnisse mit Secrets wählen.

# Schneller Vorab-Check (kopieren und ausführen)
git --version
sw_vers
df -h ~
mkdir -p ~/hermes-lab/{inbox,outbox,archive}
echo "Hermes-Lab-Beispiel: Q2-Planungsnotizen." > ~/hermes-lab/inbox/sample.txt

Bei Fehler prüfen: Git-Fehler → CLT/Homebrew; wenig Speicher → Downloads leeren oder anderes Volume; Netzwerk-Timeout → Netz wechseln oder Proxy — nicht dreimal neuinstallieren, ohne die Ursache zu kennen.

4. Offizielle Hermes-Agent-Installation

Ziel: den gepflegten Installer von Nous Research nutzen, damit Python, Node und die CLI mit erledigt werden. Quelle: offizielle Installationsdoku (vor Veröffentlichung Versionen und neue Flags erneut prüfen).

4.1 Empfohlen: Git-Einzeiler (trackt main)

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Der Installer richtet automatisch uv, Python 3.11, Node.js v22, ripgrep, ffmpeg ein, klont das Repo, erstellt ein venv und fügt hermes dem PATH hinzu. Typisches Benutzer-Layout:

• Code: ~/.hermes/hermes-agent/
• Daten & Config: ~/.hermes/ (Override mit HERMES_HOME)
• CLI: ~/.local/bin/hermes

4.2 Alternative: pip install (Python 3.11+ muss vorhanden sein)

pip install hermes-agent
hermes postinstall   # optional: Node, Browser, ripgrep, ffmpeg + Setup

PyPI folgt getaggten Releases; für Bleeding Edge den Git-Einzeiler oben bevorzugen. hermes update verhält sich je nach Installationsmethode unterschiedlich — vertrauen Sie dem, was hermes doctor meldet.

4.3 Drei Pflichtschritte nach der Installation

source ~/.zshrc          # oder neues Terminalfenster öffnen
hermes version           # Version notieren für spätere Fehlersuche
hermes doctor            # Lücken automatisch finden; --fix für Reparaturversuche

Abnahmekriterium: which hermes zeigt auf ~/.local/bin/hermes; hermes doctor ohne blockierendes FAIL. Bei Fehler prüfen: letzte 20 Zeilen Install-Log → PATH → ob Sie das rohe Repo-hermes mit System-Python aufgerufen haben (venv-Launcher nutzen).

Nicht: bei Fehler sofort ~/.hermes löschen und neuinstallieren — Terminalausgabe und hermes doctor sichern, sonst unterscheiden Sie Netzwerk- von Berechtigungsproblemen nicht.

5. Modelle & API-Keys konfigurieren

Ziel: Hermes mit Ihrem gewählten LLM-Provider verbinden. Abnahmekriterium: nicht-interaktiver Smoke-Test liefert sinnvolle Antwort; hermes auth list oder .env enthält den Eintrag; Key nicht im Klartext in der Shell-Historie.

5.1 Interaktives Setup (beim ersten Mal empfohlen)

hermes setup          # vollständiger Assistent: Modelle, Tools, Gateway usw.
# oder Schritt für Schritt:
hermes model          # Provider und Standardmodell wählen
hermes tools          # Tool-Sets nach Bedarf aktivieren

5.2 Umgebungsvariablen & Konfigurationsdateien

Hauptconfig liegt meist unter ~/.hermes/config.yaml; Secrets werden in ~/.hermes/.env referenziert (bestätigen mit hermes config path und hermes config env-path). Beispiel (Variablennamen folgen der aktuellen Provider-Doku — keine veralteten Namen kopieren):

# Beispiel: OpenRouter (Key ersetzen; nie in Git committen)
hermes config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# oder .env direkt bearbeiten (chmod 600 ~/.hermes/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.hermes/.env

Grenzhinweis: Modellpreise, API-Limits, regionale Verfügbarkeit und Datenschutz ändern sich mit den Providern — vor Produktionseinsatz aktuelle Bedingungen lesen. Dieser Artikel bindet Sie nicht an einen Modellnamen fest.

6. Workspace, Berechtigungen & Logs

Ziel: nach der Installation nachvollziehbar, begrenzt und rollback-fähig arbeiten. Prinzip: minimale Rechte — zuerst nur Testverzeichnis, dann schrittweise echte Projekte.

• Workspace: ~/hermes-lab in config.yaml oder der Sitzung setzen; dort AGENTS.md mit erlaubten Tools und Grenzen (siehe offizielle Context-Files-Doku).
• macOS-Berechtigungen: Terminal-/Datei-Tools können Vollzugriff anfragen — bei Erstabnahme nur das für das Testverzeichnis Nötige, nicht ganze Festplatte.
• Log-Verzeichnis: Standard ~/.hermes/logs/ (agent.log, errors.log, gateway.log). Prüfen mit hermes logs list, hermes logs errors --since 30m.
• Secret-Hygiene: chmod 600 ~/.hermes/.env; Backup-Zips nicht in Sync-Ordner; Agent nie ~/.ssh, Zahlungsdaten oder Produktions-kubeconfig lesen lassen.
• Hintergrundbetrieb (optional): für Telegram-/Discord-Gateways hermes gateway setup und hermes gateway install; Langzeit-Ops in unserem Hermes-Langzeit-Wartungsleitfaden.

Abnahmekriterium: nach Anweisung „nur ~/hermes-lab lesen/schreiben“ werden Zugriffe außerhalb der Testpfade verweigert oder protokolliert.

7. Erstabnahme: Sieben-Schritte-Runbook

Diese sieben Schritte führen von „Konfiguration abgeschlossen“ zu „produktionsreif“ — der Reihe nach ausführen und Screenshots oder Log-Ausschnitte aufbewahren.

1. Diagnose: hermes doctor --fix → kein offenes FAIL.
2. Modell-Ping: hermes chat -q "Antworte exakt mit: HERMES_OK" → Antwort enthält HERMES_OK.
3. Datei lesen: Agent liest ~/hermes-lab/inbox/sample.txt und wiederholt den ersten Satz.
4. Datei schreiben: schreibt ~/hermes-lab/outbox/ping.txt → mit cat sichtbar.
5. Logs: hermes logs errors --since 10m → kein neues ERROR (oder dokumentierte harmlose Einträge).
6. Terminal schließen: Fenster beenden, neues öffnen, Schritt 2 wiederholen → schließt PATH-nur-in-dieser-Sitzung aus.
7. Optional Neustart: Mac neu starten, Schritt 2 erneut (bei installiertem Gateway zusätzlich hermes gateway status).

Referenzschwellen (persönliche Abnahme, kein offizielles SLA): Smoke-Antwort < 60 s; 0 unerklärte ERROR-Zeilen in errors.log in 10 Minuten; nach Test-Schreiben zeigt ls -la ~/hermes-lab/outbox die neue Datei.

8. Erstes Praxisbeispiel: Zusammenfassung + Todos + rollback-fähige Ausgabe

Szenario: Beispieltext im Testverzeichnis lesen, deutsche Zusammenfassung und drei Todos erzeugen, Markdown-Ausgabe schreiben und Rollback-Kopie behalten. Das Beispiel deckt Installationsergebnis (CLI), Konfigurationsergebnis (Modell) und einen echten Workflow (lesen → denken → schreiben → Logs) ab.

# 1. Eingabe vorbereiten (überspringen, wenn Abschnitt 3 schon erledigt)
cat > ~/hermes-lab/inbox/weekly-notes.txt <<'EOF'
Diese Woche: Entwurf der Hermes-Installationsdoku fertiggestellt.
Follow-ups: OpenRouter-Budget-Alerts konfigurieren; Telegram-Gateway nächste Woche evaluieren.
Risiko: API-Keys niemals in Git committen.
EOF

# 2. Interaktive Sitzung starten (oder eine zusammengesetzte Anweisung)
hermes
# In der Sitzung senden (Beispiel-Prompt):
# "Nur ~/hermes-lab verwenden. Lies inbox/weekly-notes.txt,
#   schreibe eine Zusammenfassung unter 150 Wörter plus 3 Todos auf Deutsch,
#   speichere in outbox/summary-and-todos.md,
#   und kopiere die Originaldatei nach archive/weekly-notes.bak"

# 3. Nicht-interaktive Verifikation
ls -la ~/hermes-lab/outbox/summary-and-todos.md
ls -la ~/hermes-lab/archive/
hermes logs agent -n 30 --since 15m

Abnahmekriterien:

• summary-and-todos.md enthält Zusammenfassung und drei Todos passend zur Quelldatei.
• archive/ hält ein Backup für diff.
• Logs zeigen passende Tool-Aufrufe; Provider-Abrechnung/Dashboard spiegelt diesen Lauf wider (Kostenverifikation).

Rollback: rm ~/hermes-lab/outbox/summary-and-todos.md && cp ~/hermes-lab/archive/weekly-notes.bak ~/hermes-lab/inbox/weekly-notes.txt. Bei Fehler prüfen: Modell hat Datei abgeschnitten → Berechtigung outbox verweigert → Tool-Fehler in errors.log.

9. Fehlerbehebung: schichtweise, ohne blindes Neuinstallieren

Fakten-Checkliste vor Veröffentlichung (Redaktion): offizielle install.sh-URL, Mindest-macOS, Standardverzeichnisse, CLI-Subcommands, Provider-Env-Variablen, Log-Pfade — bei Änderungen Artikel aktualisieren. Leser merken sich: bei Fehler hermes doctor, dann errors.log, erst dann Neuinstallation erwägen.

10. Nächste Schritte: vom Testverzeichnis zu echten Workflows

Nach bestandener Abnahme in dieser Reihenfolge erweitern — nicht direkt auf Produktions-Repos oder Zahlungssysteme springen:

1. Ein echtes Nebenprojekt-Verzeichnis zur Allowlist hinzufügen; weiterhin ~/.ssh und globales * Lese/Schreiben blockieren.
2. hermes cron für tägliche risikoarme Aufgaben aktivieren (z. B. Downloads inventarisieren — weiter auf Testverzeichnisse begrenzt).
3. Ein Messaging-Gateway (Telegram/Discord) mit Pairing-Modus konfigurieren, um Fremde abzuwehren (offizielle Security-Doku).
4. Wöchentlichen Rhythmus mit hermes backup --quick etablieren, dann Langzeit-Wartungsleitfaden für Upgrade- und Rollback-Drills lesen.