Eigener KI-Agent im Selbstbau, Teil 1: Hermes als Docker-Container mit Telegram

Das ist Teil 1 der Serie Dein eigener KI-Agent im Selbstbau. Im Teaser habe ich beschrieben, was so ein selbstgehosteter Agent kann und für wen er Sinn macht. Jetzt bauen wir das Grundgerüst, sauber als Docker-Container.

Am Ende dieses Teils läuft auf deinem Rechner ein eigener KI-Agent in einem Docker-Container, verbunden mit OpenRouter, und du erreichst ihn von überall per Telegram am Handy. Die Weboberfläche Open WebUI mit deinen eigenen Dokumenten kommt in Teil 2. Rechne mit etwa 45 Minuten.

Was am Ende läuft

Das ist das Gesamtbild der Serie. Hermes Agent ist die Schicht, die Werkzeuge bedient und sich Lösungswege merkt, und spricht mit dem Modell bei OpenRouter. In diesem Teil bauen wir genau diesen Kern als Container und machen ihn über Telegram erreichbar. Die Weboberfläche Open WebUI hängt sich in Teil 2 davor, und auch deine eigenen Dokumente kommen dort dazu.

Voraussetzungen

• Ein Mac (ich mache es auf einem Mac mini M4 mit 16 GB), Linux oder Windows mit WSL2 geht genauso
• Docker Desktop
• Ein kostenloser OpenRouter-Account mit etwas Guthaben
• Etwa 60 Minuten

Schritt 1: Docker Desktop installieren

Lade Docker Desktop von docker.com und starte es, bis unten links “Engine running” grün leuchtet. Unser ganzer Stack läuft als Container darin.

Schritt 2: OpenRouter-Account und API-Key

Leg dir auf openrouter.ai einen Account an, erstelle unter den API-Keys einen neuen Schlüssel und kopiere ihn (er beginnt mit sk-or-). Lad etwas Guthaben auf, ein paar Euro reichen für lange. Über OpenRouter hast du Zugriff auf über 200 Modelle, du zahlst nur, was du nutzt.

Schritt 3: Das Hermes-Image holen

Hermes gibt es als fertiges Docker-Image, du musst nichts aus dem Quellcode bauen. Hol es mit:

docker pull nousresearch/hermes-agent:latest
Kopieren

Das lädt etwa 1,1 GB, ein nativer Build für Apple Silicon, also voll schnell auf dem M4. Nach ein paar Minuten liegt es lokal.

Schritt 4: Hermes einrichten (Setup-Wizard im Container)

Bevor der Agent dauerhaft läuft, braucht er einmal eine Konfiguration: Anbieter, Schlüssel, Modell. Das macht der Setup-Wizard. Du startest ihn einmalig in einem Container, der dein Konfigurationsverzeichnis ~/.hermes einbindet:

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

Alles, was du jetzt einstellst, landet in ~/.hermes und bleibt erhalten. Das Image selbst bleibt zustandslos, du kannst es später einfach gegen eine neuere Version tauschen, ohne die Konfiguration zu verlieren.

Die erste Frage ist, wie ausführlich du einrichten willst:

Nimm Quick setup (empfohlen). Der geht der Reihe nach Provider, Modell und Messaging durch, navigiert wird mit den Pfeiltasten, ausgewählt mit Enter. “Full setup” konfiguriert alles im Detail, das hebst du dir für später auf.

Provider wählen

Gleich danach fragt Hermes, über welchen Anbieter die Modelle laufen sollen. Die Liste ist lang, vorausgewählt ist das Nous Portal:

Für diese Serie nimmst du OpenRouter (100+ models, pay-per-use). Damit hast du mit einem einzigen Schlüssel Zugriff auf sehr viele Modelle und zahlst nur, was du nutzt, genau das, was wir in Schritt 2 vorbereitet haben.

Die anderen Optionen kurz eingeordnet:

• Nous Portal ist der hauseigene Abo-Zugang von Nous Research, den Machern von Hermes. Ein Abo bündelt viele Modelle und fertige Werkzeuge wie Websuche, Bildgenerierung und Sprachausgabe unter einem Login, interessant, wenn du dir das Verkabeln einzelner Dienste sparen willst.
• Anthropic oder OpenAI direkt, wenn du schon einen eigenen Key für genau einen Anbieter hast und nichts dazwischen willst.
• LM Studio oder Ollama Cloud für den Weg über lokale oder offene Modelle, das vertiefen wir in Teil 4.

Mit OpenRouter bleibst du am flexibelsten, weil du das Modell jederzeit wechselst, ohne den Anbieter zu tauschen.

Datenschutz-Hinweis zu OpenRouter: OpenRouter ist eine US-Firma. Deine Anfragen laufen über US-Server, bevor sie an den eigentlichen Modell-Anbieter weitergehen. Für viele Fälle ist das in Ordnung. Wenn du aber aus DSGVO-Gründen in der EU bleiben willst, ist OpenRouter nicht der richtige Weg, auch dann nicht, wenn du ein EU-Modell auswählst.

Für echte EU-Datenresidenz überspringst du OpenRouter und zeigst direkt auf einen EU-Anbieter wie Mistral. Dafür legst du dir vorab bei Mistral einen eigenen API-Key an.

model:
  default: mistral-large-latest
  provider: custom
  base_url: https://api.mistral.ai/v1
  api_key: dein-mistral-key
Kopieren

Key und Modell

Sobald du OpenRouter ausgewählt hast, fügst du gleich deinen API-Key ein (der aus Schritt 2, beginnt mit sk-or-). Danach zeigt Hermes eine Liste der Modelle samt Preisen pro Million Token, getrennt nach Eingabe, Ausgabe und Cache:

Bevor du wählst, lohnt ein Blick darauf, wer hinter den Modellen steht. Über OpenRouter geht deine Anfrage an den jeweiligen Anbieter, und das ist für den Datenschutz nicht egal.

Vorausgewählt ist das stärkste und teuerste, Claude Opus. Für den Alltag brauchst du das selten. Gerade für einen Agenten, der viel mit Werkzeugen arbeitet, gibt es deutlich günstigere Modelle, die sehr gut mithalten:

• Bestes Preis-Leistungs-Verhältnis für Agenten: Kimi K2.6 ($0.68 / $3.42) und Qwen3.7-Max ($1.25 / $3.75). Beide gelten 2026 als stark beim Tool-Use und bei mehrstufigen Aufgaben, zu einem Bruchteil der Kosten der Spitzenmodelle.
• Maximal verlässlich: Claude Sonnet 4.6 ($3 / $15) oder Opus, wenn du das vorhersehbarste Verhalten willst und der Preis keine Rolle spielt.
• Sehr billig für Einfaches: DeepSeek V4 Flash ($0.10 / $0.20), Gemini 3.5 Flash oder Qwen3.6-35B.
• Gratis zum Testen: owl-alpha oder das Nemotron-Free-Modell, mit Limits.

Mein Tipp: Fang mit Kimi K2.6 oder Qwen3.7-Max an, das ist für Agenten-Aufgaben ein sehr gutes Preis-Leistungs-Verhältnis. Wechseln kannst du später jederzeit mit docker exec -it hermes hermes model.

Ein Muss: Hermes braucht ein Modell mit mindestens 64.000 Token Kontext, sonst lehnt es beim Start ab. Die großen Modelle in der Liste erfüllen das alle.

Terminal-Backend wählen

Als Nächstes fragt Hermes, wo der Agent seine Befehle ausführt:

Wichtig zum Einordnen: Diese Wahl betrifft nur, wo der Agent Befehle und Code ausführt. Deine Dokumente-Funktion und die Websuche hängen nicht davon ab, die laufen über Open WebUI und die Tools des Agenten.

In unserem Aufbau läuft Hermes selbst schon in einem Container. Wähl deshalb Local: Der Agent führt seine Befehle dann innerhalb des Hermes-Containers aus, also von Natur aus abgeschottet vom Rest deiner Maschine. Die anderen Optionen (eigener Docker-Sandbox, Cloud, SSH) sind für Spezialfälle.

Telegram anbinden, dein Agent aufs Handy

Zum Schluss fragt der Assistent nach einer Messaging-Plattform. Das ist der schnellste Weg, den Agenten von überall am Handy zu nutzen, ganz ohne Port-Freigabe oder HTTPS, weil Hermes über Long Polling von sich aus bei Telegram anfragt. Wenn du nur die Weboberfläche willst, kannst du hier überspringen und Telegram später nachrüsten.

Für Telegram holst du dir vorher zwei Dinge in der Telegram-App.

1. Bot-Token über @BotFather: Sende /newbot, wähl einen Anzeigenamen und einen Usernamen, der auf bot endet. BotFather schickt dir dann den Token, er sieht aus wie 123456789:ABCdef....

2. Deine User-ID über @userinfobot: Schreib ihn an, er antwortet sofort mit deiner numerischen ID.

Dann im Wizard die Plattform Telegram auswählen: mit der Leertaste anhaken, mit Enter bestätigen.

Danach fragt der Wizard nach dem Token und den allowed users. Beim Token fügst du den BotFather-Token ein. Bei allowed users kommt deine eigene numerische User-ID hin, also die Zahl von @userinfobot (z.B. 123456789), nicht der Bot-Name. Leer lassen würde den Bot für jeden öffnen, das willst du nicht.

Die anschließende Frage “Use your user ID as the home channel? [Y/n]” beantwortest du mit Y. Der Home Channel ist, wohin Hermes dir von sich aus schreibt, also Ergebnisse geplanter Aufgaben und Benachrichtigungen. Bei Telegram ist das deine eigene DM.

Sicherheit, und das ist Pflicht: Trag bei allowed users nur deine eigene ID ein. Dein Agent kann echte Befehle ausführen, der Bot darf also nicht für Fremde offen sein. Weitere Personen ergänzt du später mit Komma getrennt.

Der Wizard schreibt Token und erlaubte IDs nach ~/.hermes/.env. Online geht der Bot erst, wenn der Gateway läuft, also nach Schritt 6. Eine Änderung an der Compose brauchst du dafür nicht: Der Gateway liest den Token aus dem gemounteten ~/.hermes und bedient Telegram und den API-Server für Open WebUI gleichzeitig.

✅ Checkpoint: Am Ende zeigt der Wizard “Ready to go!” und du bist zurück am normalen Prompt. Deine Konfiguration, also Modell, OpenRouter-Key und Telegram, liegt jetzt in ~/.hermes.

Schritt 5: Hermes als Container dauerhaft starten

Bisher hast du Hermes nur einmalig zum Einrichten gestartet. Jetzt soll der Agent dauerhaft im Hintergrund laufen und nach einem Neustart von selbst wiederkommen. Dafür legst du eine docker-compose.yml an, die die Container-Konfiguration an einer Stelle hält.

Leg einen Projektordner an:

mkdir -p ~/ki-heimserver && cd ~/ki-heimserver
Kopieren

Und die docker-compose.yml:

cat > docker-compose.yml <<'YAML'
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: ["gateway", "run"]
    volumes:
      - ~/.hermes:/opt/data
YAML
Kopieren

Kurz erklärt: Der Container startet den Hermes-Gateway (gateway run), bindet deine Konfiguration aus ~/.hermes ein und kommt dank restart: unless-stopped nach einem Neustart automatisch wieder. Mehr braucht Teil 1 nicht. Der Gateway liest deinen Telegram-Token aus ~/.hermes und geht damit online. Die Weboberfläche Open WebUI und der API-Server kommen in Teil 2 dazu.

Schritt 6: Hochfahren

docker compose up -d
docker compose logs -f hermes
Kopieren

docker compose up -d startet den Container im Hintergrund. logs -f zeigt dir live, wie der Gateway hochfährt und sich mit Telegram verbindet. Sobald eine Zeile Richtung Telegram bzw. Gateway-online erscheint, beendest du das Mitlesen mit Ctrl+C, der Container läuft weiter.

Schritt 7: Prüfen

docker compose ps
Kopieren

✅ Checkpoint: Der Container hermes steht auf “running” (bzw. “Up”).

Den Status siehst du auch in Docker Desktop unter Containers, dort taucht dein Stack als Gruppe ki-heimserver auf. Über die Oberfläche kannst du bequem Logs ansehen, neu starten oder stoppen. Andere Container, die du dort eventuell siehst, etwa eine Datenbank aus einem anderen Projekt, gehören nicht zu unserem Setup und kannst du ignorieren.

Schritt 8: Dein Agent am Handy

Jetzt der Moment, auf den alles hinauslief. Öffne deinen Bot in der Telegram-App, du findest ihn unter dem Usernamen, den du bei BotFather vergeben hast, und schreib ihm. Er antwortet innerhalb von Sekunden, von überall, auch wenn du nicht im Heimnetz bist.

Stell ihm eine Frage, die ein Werkzeug braucht, etwa eine kurze Web-Recherche. Du siehst, wie Hermes mitdenkt und Schritte ausführt, bevor die Antwort kommt.

Antwortet der Bot nicht? Schau in die Logs mit docker compose logs hermes. Steht dort eine Zeile wie Unauthorized user: 123456789, dann ist genau diese ID nicht in deiner Allowlist, meist ein Tippfehler bei der User-ID. Öffne ~/.hermes/.env, trag bei TELEGRAM_ALLOWED_USERS exakt die ID aus dem Log ein (der Home Channel steht ebenfalls in dieser Datei), dann docker compose restart hermes. Das ist der häufigste Stolperstein an dieser Stelle.

Wenn das funktioniert, steht dein Kern: ein eigener KI-Agent, der in einem Container läuft und von deinem Handy aus erreichbar ist.

Häufige Fallstricke

Ein Wort zur Sicherheit

In Teil 1 ist nach außen nichts offen: Hermes verbindet sich nur ausgehend zu Telegram und OpenRouter, es gibt keinen offenen Port. Der wichtige Punkt ist die Telegram-Allowlist, also dass nur deine eigene User-ID den Bot bedienen darf, denn der Agent kann echte Befehle ausführen. Hermes läuft zudem im Container, also abgeschottet vom Rest der Maschine.

Dauerbetrieb: Autostart nach einem Neustart

Ein Heimserver soll nach einem Stromausfall oder Neustart von selbst wiederkommen. Das restart: unless-stopped in der Compose holt zwar den Container zurück, aber nur, wenn Docker läuft. Und Docker Desktop ist auf dem Mac eine normale App, kein Systemdienst, es startet nach einem Reboot nicht von allein. Damit die Kette geschlossen ist, brauchst du drei Dinge:

1. Automatische Anmeldung in macOS: Systemeinstellungen → Benutzer:innen & Gruppen → „Automatisch anmelden als …" → dein Benutzer. So landet der Mac nach dem Neustart direkt in deiner Sitzung.
2. Docker Desktop beim Anmelden starten: Docker Desktop → Einstellungen → General → „Start Docker Desktop when you sign in" aktivieren.
3. restart: unless-stopped steht schon in unserer Compose und bringt dann den Hermes-Container automatisch zurück.

Mit diesen drei Schritten fährt nach einem Neustart alles von selbst wieder hoch, Docker braucht dafür nur ein, zwei Minuten.

Zwei kurze Hinweise: Mit aktiver Festplattenverschlüsselung (FileVault) klappt die automatische Anmeldung nicht, und große macOS-Updates wollen manchmal einen manuellen Klick. Den sauberen Produktionsbetrieb und die headless-Variante unter Linux schauen wir uns in Teil 5 an.

Was du jetzt hast

Auf deinem Mac mini läuft ein eigener KI-Agent in einem Docker-Container. Er nutzt über OpenRouter ein starkes Modell, du erreichst ihn von überall als Telegram-Chat am Handy, und nur du darfst ihn bedienen. Kein Abo pro Person, kein fremder Anbieter, der die Regeln ändert. Der Agent gehört dir, und er läuft dauerhaft im Hintergrund, auch nach einem Neustart.

Schon jetzt kannst du ihn wie einen persönlichen Assistenten nutzen: Fragen stellen, dir Dinge erklären lassen, Texte entwerfen, Ideen durchgehen. Die ganze Werkzeug- und Automatisierungs-Kraft, also eigene Fähigkeiten, Mail und geplante Aufgaben, bauen wir in den nächsten Teilen aus.

Was er sich merkt

Eine Sache hebt diesen Agenten von einem normalen Chatbot ab: Hermes ist als Agent ausgelegt, der mit der Nutzung wächst. Er hat einen Gedächtnis-Layer, der über einzelne Unterhaltungen hinaus festhält, was du mit ihm besprichst, gespeichert in deinem ~/.hermes-Verzeichnis, also auf deinem Gerät, und er übersteht jeden Neustart des Containers. Mit der Zeit merkt er sich, wie du arbeitest und was dir wichtig ist.

Was er jetzt noch nicht kennt, sind deine eigenen Dokumente. Verträge, Angebote, Handbücher, das weiß er noch nicht. Genau das holen wir in Teil 2 herein, als private Wissensbasis, aus der er gezielt antwortet.

Wie es weitergeht

Damit steht das Fundament. So geht die Reise weiter:

• Teil 2: Open WebUI als Weboberfläche anbinden und deine eigenen Dokumente einbringen, private Wissensräume, mehrere Nutzer sauber getrennt. Der Teil, der das Setup für Familie und Firma interessant macht.
• Teil 3: Hermes als echter Agent, eigene Fähigkeiten, ein Mail-Agent und automatisierte Aufgaben.
• Teil 4: Erweiterungen wie Websuche, Sprache und Bilder, dazu lokale Modelle für den Betrieb ganz ohne Cloud.
• Teil 5: Produktionsbetrieb, sicherer Fernzugriff per HTTPS, Datenbank und Backups.

Wenn du so ein Setup für deine Firma aufsetzen oder die Mehrbenutzer-Trennung sauber aufziehen willst, kannst du mich bei Fragen jederzeit kontaktieren.