Hermes Agent einrichten – Der Praxiseinstieg

Als ich vor einigen Monaten von Claude auf Hermes Agent umgestiegen bin, gab es genau ein Problem: Die Dokumentation war gut, aber mir fehlte ein praxisnaher Einstieg, der nicht nur die Basics abdeckt, sondern auch die typischen Fallstricke, in die man als Neueinsteiger garantiert tappt. Diesen Guide hätte ich damals gebraucht – jetzt schreibe ich ihn selbst.

Was ist Hermes Agent überhaupt?

Hermes Agent ist ein von Nous Research entwickelter, quelloffener AI-Agent, der auf eurem eigenen Rechner oder Server läuft. Anders als viele Cloud-basierte Assistenten (ChatGPT, Claude) läuft Hermes komplett lokal – oder auf einem von euch kontrollierten Server. Das bedeutet: volle Datenhoheit, kein Abo-Zwang, und die Möglichkeit, das System mit eigenen Skills und Plugins zu erweitern.

Ich nutze Hermes Agent täglich für Coding, Recherche, Dateimanagement und automatisierte Cron-Workflows. Inzwischen habe ich über 15 Skills gebaut, die mir jede Woche Stunden sparen. Aber fangen wir von vorne an.

Installation Schritt für Schritt

Ich installiere Hermes Agent auf einem Ubuntu-24.04-Server mit 32 GB RAM und einer RTX 4070. Für den Einstieg reichen aber auch 16 GB RAM und eine beliebige GPU – oder sogar CPU-only, wenn ihr Cloud-APIs (DeepSeek, OpenAI) als Backend nutzt.

Schritt 1: Abhängigkeiten

# System-Pakete installieren
sudo apt update && sudo apt upgrade -y
sudo apt install python3.11 python3.11-venv git curl build-essential -y

# Python 3.11 als Standard setzen
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

Schritt 2: Hermes Agent installieren

# Projektverzeichnis anlegen
mkdir -p ~/hermes-agent && cd ~/hermes-agent

# Virtuelle Umgebung
python3 -m venv .venv
source .venv/bin/activate

# Hermes installieren (via pip)
pip install hermes-agent

# Oder direkt von GitHub für den neuesten Stand:
pip install git+https://github.com/NousResearch/hermes-agent.git

Bei mir lief die GitHub-Installation problemlos durch. Falls ihr auf fehlende System-Bibliotheken stoßt: sudo apt install libssl-dev libffi-dev behebt die häufigsten Fehler.

Schritt 3: Basis-Konfiguration

# Erstkonfiguration starten
hermes-agent init

# Das erzeugt ~/.hermes/config.yaml
# Öffnet die Config:
nano ~/.hermes/config.yaml

Meine produktive config.yaml sieht so aus:

provider: deepseek
model: deepseek-v4-pro
api_key: ${DEEPSEEK_API_KEY}
max_tokens: 32000
temperature: 0.3

skills_dir: ~/.hermes/skills
plugins_dir: ~/.hermes/plugins
cron_dir: ~/.hermes/cron
memory_dir: ~/.hermes/memories

logging:
  level: info
  file: ~/.hermes/hermes.log

Der erste Skill

Skills sind das Herzstück von Hermes Agent. Ein Skill ist im Kern eine YAML-Datei mit einer System-Prompt-Beschreibung plus optionalen Python-Hooks. Mein erster Skill war ein simpler "Datei-Organizer":

# ~/.hermes/skills/file-organizer/skill.yaml
name: file-organizer
description: >
  Organisiert Dateien im angegebenen Verzeichnis nach Typ.
  Verschiebt Bilder nach /images, Dokumente nach /docs,
  Code nach /src, Archive nach /archives.
  Erkennt über 50 Dateitypen automatisch.

parameters:
  directory:
    type: string
    description: Pfad zum zu organisierenden Verzeichnis
    required: true
  dry_run:
    type: boolean
    description: Nur Vorschau ohne tatsächliches Verschieben
    default: false

exec:
  type: python
  entry: organize.py

# ~/.hermes/skills/file-organizer/organize.py
import os, shutil
from pathlib import Path

TYPE_MAP = {
    '.jpg': 'images', '.png': 'images', '.gif': 'images', '.webp': 'images',
    '.pdf': 'docs', '.docx': 'docs', '.md': 'docs', '.txt': 'docs',
    '.py': 'src', '.js': 'src', '.ts': 'src', '.go': 'src', '.rs': 'src',
    '.zip': 'archives', '.tar.gz': 'archives', '.7z': 'archives',
}

def run(directory: str, dry_run: bool = False) -> dict:
    path = Path(directory).expanduser()
    moved = []
    for file in path.iterdir():
        if file.is_file():
            ext = file.suffix.lower()
            target_dir = TYPE_MAP.get(ext, 'misc')
            dest = path / target_dir / file.name
            if not dry_run:
                dest.parent.mkdir(exist_ok=True)
                shutil.move(str(file), str(dest))
            moved.append(f"{file.name} → {target_dir}/")
    return {"moved": len(moved), "files": moved, "dry_run": dry_run}

Nach dem Anlegen ist der Skill sofort verfügbar. Hermes scannt das skills_dir beim Start und lädt alle gefundenen Skills automatisch.

Typische Fallstricke – und wie ihr sie vermeidet

1. "Der Agent versteht meinen Skill nicht"

Das Problem hatte ich bei meinen ersten 3 Skills. Die Lösung: Die description im YAML muss extrem präzise sein. Beschreibt nicht nur, was der Skill tut, sondern auch wann er eingesetzt werden soll. Meine ursprüngliche Beschreibung "Organisiert Dateien" führte dazu, dass Hermes den Skill nie aufrief. Erst mit "Organisiert Dateien im angegebenen Verzeichnis nach Typ. Verwende diesen Skill, wenn der Benutzer seinen Downloads-Ordner oder ein Projektverzeichnis aufräumen möchte" funktionierte es.

2. Pfade unter Windows

Wenn ihr – wie ich anfangs – unter Windows entwickelt, achtet auf die Pfadkonvention. Hermes läuft in einer MSYS/Bash-Umgebung. /c/Users/vcrom/... und C:\Users\vcrom\... funktionieren beide, aber nicht gemischt im selben Skill. Ich verwende konsequent Unix-Pfade mit pathlib, das löst 99% der Probleme.

3. Rate-Limits bei Cloud-APIs

Bei intensiver Nutzung mit vielen Tool-Calls (jeder Tool-Call zählt als API-Request) stößt man schnell an Rate-Limits – besonders bei DeepSeek. Mein Workaround: Ein Retry-Wrapper mit exponential Backoff:

import time
import random

def retry_with_backoff(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
    raise Exception("Max retries exceeded")

Fazit: Lohnt sich der Umstieg?

Nach 3 Monaten mit Hermes Agent kann ich sagen: Ja, absolut. Die Flexibilität durch eigene Skills, die volle Datenkontrolle und die Tatsache, dass ich nicht an ein einzelnes Modell gebunden bin (heute DeepSeek, morgen vielleicht ein lokales Llama-4), machen Hermes zu meinem täglichen Treiber. Der initiale Setup-Aufwand von etwa 2–3 Stunden zahlt sich innerhalb der ersten Woche aus.

Im nächsten Artikel vergleiche ich Self-Hosting vs. Cloud – stay tuned!