Last updated on

Hör auf, API-Keys in .env zu quetschen: In 5 Schritten zu Hermes v0.19s neuem externen Secret-Vault

Wie viele API-Keys liegen aktuell in deiner ~/.hermes/.env? OpenAI, Anthropic, GitHub, Telegram, Discord, Cloudflare, AWS — jedes Mal, wenn du eine neue Integration hinzufügst, kopierst du eine weitere Zeile SOME_KEY=sk-... hinein. Dann prüfst du dreimal .gitignore, schickst dir die Datei per Slack, wenn du den Rechner wechselst, und fügst sie in CI-Secrets wieder ein. Schlimmer noch: Jeder im Team hat eine lokale Kopie, also weiß niemand, welche Version aktuell ist, wer was geändert hat oder ob ein Key geleakt wurde.

Hermes Agent v0.19.0 macht aus diesem Chaos eine saubere Abstraktion: SecretSource. Hermes kann API-Keys beim Start aus einem externen Vault lesen, mit nativem Support für Bitwarden Secrets Manager und 1Password. Du behältst ein einziges Bootstrap-Token in .env und lässt den Vault den Rest verwalten. Keys müssen nicht mehr in Klartext-.env-Dateien liegen.

Dieser Post zeigt eine praktische 5-Schritt-Migration. Du musst nicht alles auf einmal umbauen — du kannst zuerst die riskantesten Keys auslagern und gleichzeitig einen Rollback-Pfad offenhalten.

Für den vollständigen v0.19.0-Überblick sieh dir unsere v0.19.0 Release Notes und den Skill-Combo-Guide an.

Warum .env keine langfristige Lösung ist

.env ist super für Prototypen, bricht aber zusammen, sobald Hermes mit einem Dutzend Tools und Services spricht:

  1. Verbreitungsrisiko. Jedes Mal, wenn du .env auf eine andere Maschine, einen Container oder eine CI-Umgebung kopierst, entsteht eine neue Leak-Oberfläche. GitHub findet jedes Jahr Millionen versehentlich committeter Secrets.
  2. Kein Audit-Trail. .env verrät nicht, wer welchen Key wann geändert hat. Ein Key wird rotiert, und der Rest des Teams merkt es erst, wenn etwas kaputt geht.
  3. Schmerzhafte Rotation. Quartalsweise Token-Rotation bedeutet: N Dateien und N Umgebungsvariablen-Injektionspunkte bearbeiten, dann hoffen, dass nichts vergessen wurde.

Ein externer Secret-Vault löst nicht nur „Klartext verstecken“. Er macht Secrets zu kontrollierten, auditierbaren, zentral verwalteten Ressourcen. Hermes v0.19.0s SecretSource verbindet diese Idee direkt mit dem Startpfad des Agents, sodass der Agent Vault-Werte wie normale Umgebungsvariablen lesen kann.

Was Hermes v0.19.0s SecretSource kann

Laut den v0.19.0 Release Notes und der offiziellen Secrets-Doku bietet die SecretSource-Schnittstelle:

  • Mehrere Vaults gleichzeitig. Bitwarden Secrets Manager und 1Password können gleichzeitig aktiviert werden. Außerdem gibt es eine generische command-Quelle für jeden Vault, der KEY=VALUE-Zeilen ausgibt.
  • Deterministische Präzedenz. Hermes löst Konflikte nach einer klaren Leiter: Explizite env:-Mappings (1Password, command source) schlagen Bulk-Projekt-Abfragen (Bitwarden); innerhalb desselben Typs entscheidet die optionale Liste secrets.sources; .env- und Shell-Werte gewinnen standardmäßig, es sei denn, eine Quelle hat override_existing: true.
  • Konflikt-Warnungen. Wenn eine spätere Quelle eine Variable bereitstellt, die eine frühere bereits beansprucht hat, warnt Hermes statt stillschweigend zu wählen.
  • Herkunftsnachverfolgung. Jede injizierte Variable merkt sich, welche Quelle sie geliefert hat — im status-Befehl und in den Start-Logs sichtbar.
  • Nicht blockierender Start. Wenn ein Vault nicht erreichbar ist oder die Authentifizierung fehlschlägt, gibt Hermes eine einzeilige Warnung mit Handlungsempfehlung aus und startet mit den Credentials aus .env weiter.

Das bedeutet, du kannst eine Konfiguration wie diese schreiben, ohne OPENAI_API_KEY überhaupt in .env abzulegen:

secrets:
  onepassword:
    enabled: true
    env:
      OPENAI_API_KEY: "op://Private/OpenAI/api key"
      ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
    override_existing: true

Die nächsten fünf Abschnitte zeigen, wie du das umsetzt.

Schritt 1: Upgrade auf Hermes v0.19.0 und CLI prüfen

SecretSource ist ein v0.19.0-Feature, also prüfe zuerst die Version:

hermes --version

Dann prüfe, ob das Subkommando secrets existiert:

hermes secrets --help

Du solltest bitwarden, onepassword und weitere Source-Helper sehen. Falls du unter v0.19.0 bist, führe das Install-Skript aus:

# macOS / Linux / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows (PowerShell)
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Schritt 2: Vault wählen und authentifizieren

Hermes authentifiziert dich nicht selbst; es verlässt sich auf den offiziellen Flow jedes Vaults. Das musst du auf der Maschine erledigen, auf der Hermes läuft.

Option A: Bitwarden Secrets Manager

Du brauchst einen Machine Account in Bitwarden Secrets Manager, nicht die Consumer-Bitwarden-Vault. Der Machine Account ist für nicht-interaktive Workloads gedacht.

  1. In der Bitwarden Web App wechselst du zu Secrets Manager.
  2. Erstelle ein Project (z. B. Hermes keys).
  3. Füge deine Provider-Keys als Secrets hinzu. Der Name des Secrets wird zum Namen der Umgebungsvariablen, die Hermes erwartet — also OPENAI_API_KEY, ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN usw.
  4. Gehe zu Machine accounts → New machine account und gewähre Lesezugriff auf das Projekt.
  5. Unter Access tokens erstellst du einen Token (beginnt mit 0., kann danach nicht mehr angezeigt werden) und kopierst ihn.

Speichere diesen Token in ~/.hermes/.env als BWS_ACCESS_TOKEN:

BWS_ACCESS_TOKEN=0.xxx...

Die bws-Binary wird beim ersten Bedarf automatisch nach ~/.hermes/bin/ heruntergeladen — kein brew, apt oder sudo nötig.

Option B: 1Password

Installiere den offiziellen 1Password CLI (op) und prüfe, ob er funktioniert:

op --version
op whoami

Laptop / interaktiv: Melde dich mit op signin an oder aktiviere die CLI-Integration in der 1Password-App. Hermes reicht deine Session-Variablen an den op-Subprozess weiter.

Server / CI / Cron: Erstelle einen Service Account, gewähre Lesezugriff auf den relevanten Vault und speichere den Token in ~/.hermes/.env:

OP_SERVICE_ACCOUNT_TOKEN=ops_...

Sicherheitshinweis: Das Bootstrap-Token (BWS_ACCESS_TOKEN oder OP_SERVICE_ACCOUNT_TOKEN) ist selbst ein hochwertiges Credential. Halte .env außerhalb der Versionskontrolle und beschränke die Dateiberechtigungen.

Schritt 3: Setup-Assistenten ausführen und Source konfigurieren

Hermes liefert für jede Source ein eigenes CLI. Der Assistent schreibt in ~/.hermes/config.yaml (bzw. ~/.hermes/profiles/<profile>/config.yaml, falls du ein benanntes Profil verwendest).

Bitwarden

Interaktiv ausführen:

hermes secrets bitwarden setup

Oder nicht-interaktiv:

hermes secrets bitwarden setup \
  --access-token "$BWS_ACCESS_TOKEN" \
  --server-url https://vault.bitwarden.com \
  --project-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Die entstehende Konfiguration sieht so aus:

secrets:
  bitwarden:
    enabled: true
    project_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    server_url: "https://vault.bitwarden.com"
    access_token_env: BWS_ACCESS_TOKEN
    override_existing: true
    cache_ttl_seconds: 300

1Password

Führe den Assistenten aus:

hermes secrets onepassword setup

Oder mit Service-Account-Token:

hermes secrets onepassword setup \
  --account my.1password.com \
  --token-env OP_SERVICE_ACCOUNT_TOKEN \
  --token "$OP_SERVICE_ACCOUNT_TOKEN"

Dann mappe jede Umgebungsvariable auf eine op://-Referenz:

hermes secrets onepassword set OPENAI_API_KEY    "op://Private/OpenAI/api key"
hermes secrets onepassword set ANTHROPIC_API_KEY "op://Private/Anthropic/credential"
hermes secrets onepassword set TELEGRAM_BOT_TOKEN "op://Private/Telegram/token"

Die entstehende Konfiguration:

secrets:
  onepassword:
    enabled: true
    env:
      OPENAI_API_KEY: "op://Private/OpenAI/api key"
      ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
      TELEGRAM_BOT_TOKEN: "op://Private/Telegram/token"
    service_account_token_env: OP_SERVICE_ACCOUNT_TOKEN
    override_existing: true
    cache_ttl_seconds: 300

Beide Sources gleichzeitig

Du kannst beide gleichzeitig aktivieren. Die Reihenfolge steuerst du über die Liste sources:

secrets:
  sources: [onepassword, bitwarden]
  onepassword:
    enabled: true
    env:
      OPENAI_API_KEY: "op://Private/OpenAI/api key"
  bitwarden:
    enabled: true
    project_id: "..."

Beachte: Gemappte Sources (1Password) haben automatisch Vorrang vor Bulk-Sources (Bitwarden), unabhängig von der Reihenfolge. Innerhalb desselben Typs gewinnt die erste Source in der Liste.

Schritt 4: Klartext-API-Keys in den Vault migrieren

4.1 Bestand der .env erfassen

Liste die Secrets auf, die Hermes aktuell nutzt, gruppiert nach Schadenspotential:

  • Modell-API-Keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY usw.
  • Platform-Tokens: TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN
  • Cloud-Credentials: AWS_ACCESS_KEY_ID, CLOUDFLARE_API_TOKEN, GCP_API_KEY
  • Third-Party-Tools: GitHub PATs, Sentry DSNs, Stripe-Keys usw.

4.2 Secrets im Vault anlegen

Bitwarden: Erstelle im ausgewählten Projekt je ein Secret pro Umgebungsvariable. Der Name muss exakt mit dem Variablennamen übereinstimmen, den Hermes erwartet, z. B. OPENAI_API_KEY. hermes secrets bitwarden sync zeigt dann, welche Variablen aufgelöst werden können.

1Password: Erstelle Items und Felder, die auf deine op://vault/item/field-Referenzen passen. Wenn du z. B. OPENAI_API_KEY auf op://Private/OpenAI/api key gemappt hast, brauchst du ein Item OpenAI im Vault Private mit einem Feld api key.

Migrations-Reihenfolge: Verschiebe zuerst die Keys mit dem größten Schadenspotential (Stripe, AWS-Root-äquivalente, primäre Modell-Provider-Keys), dann weniger riskante Read-only-Keys.

4.3 .env verkleinern und example.env anlegen

Sobald ein Key im Vault lebt, lösche oder kommentiere ihn in .env aus. Behältnis nur das Bootstrap-Token, das die Source braucht:

# ~/.hermes/.env
BWS_ACCESS_TOKEN=0.xxx...
# oder für 1Password:
# OP_SERVICE_ACCOUNT_TOKEN=ops_...

Erstelle ein example.env mit Variablennamen und Kommentaren, aber ohne echte Werte:

# example.env — echte Werte liegen im externen Vault
OPENAI_API_KEY=see-vault
ANTHROPIC_API_KEY=see-vault
TELEGRAM_BOT_TOKEN=see-vault

Neue Teammitglieder wissen so, welche Variablen erwartet werden und welchen Vault sie konsultieren müssen, ohne dass jemand eine echte .env verschickt.

Schritt 5: Verifizieren, rotieren und Rollback-Pfad offenhalten

5.1 Verifizieren, dass die Integration aktiv ist

Bitwarden:

hermes secrets bitwarden status
hermes secrets bitwarden sync        # Dry-Run: Vorschau der anwendbaren Variablen
hermes secrets bitwarden sync --apply  # in aktuelle Shell exportieren

1Password:

hermes secrets onepassword status
hermes secrets onepassword sync        # Dry-Run
hermes secrets onepassword sync --apply  # in aktuelle Shell exportieren

Starte einen neuen Hermes-Prozess (oder Cron-Job, oder Gateway-Service), damit die aufgelösten Werte übernommen werden. Du kannst die Herkunft im Start-Log oder im status-Befehl der Source bestätigen.

5.2 Rotations-Erinnerungen einrichten

Die meisten Vaults erlauben ein Feld oder eine Notiz mit dem Rotationsdatum. Setze dir einen 90-Tage-Kalender-Eintrag. Wenn sich ein Provider-Key ändert, aktualisierst du ihn nur im Vault — sonst nichts. Der nächste Hermes-Start verwendet automatisch den neuen Wert.

Wenn das Bootstrap-Token selbst leakt oder abläuft, rotiere ihn ohne erneuten Assistenten:

hermes secrets bitwarden token
hermes secrets onepassword token

Beide Befehle prüfen den Token vor dem Speichern, sodass ein Fehler beim Einfügen die aktuelle Konfiguration nicht zerstört.

5.3 Rollback-Pfad offenhalten

Zieh nicht auf einmal alle Keys raus. Eine sicherere Sequenz:

  1. Canary-Migration: Verschiebe einen unkritischen Key (z. B. eine read-only Search-API) in den Vault und prüfe, ob alles läuft.
  2. Dual-Write-Beobachtung: Halte Vault und .env parallel befüllt, aber aktiviere override_existing: true auf der Source. Beobachte ein paar Tage.
  3. Saubere Bereinigung: Wenn alles stabil ist, lösche die echten Keys aus .env und behalte nur das Bootstrap-Token.

Falls etwas schiefgeht, ist der schnellste Rollback das Deaktivieren der Source:

hermes secrets bitwarden disable
hermes secrets onepassword disable

Hermes fällt sofort auf die Credentials aus .env zurück.

Häufige Fallstricke

  1. Echte Secrets in config.yaml ablegen. config.yaml sollte nur Referenzen (op://...) und Project-IDs enthalten. Echte Werte gehören in den Vault.

  2. Das Bootstrap-Token des Vaults in einer geteilten .env committen. BWS_ACCESS_TOKEN und OP_SERVICE_ACCOUNT_TOKEN sind hochwertige Bearer-Tokens. Halte .env außerhalb der Versionskontrolle und beschränke die Dateiberechtigungen.

  3. Annehmen, .env verliert automatisch. Standardmäßig gewinnen .env und Shell-Exporte. Wenn eine Source override_existing: false hat und in .env noch alte Keys liegen, verwendet Hermes weiterhin die .env-Werte. Setze override_existing: true, wenn der Vault die Quelle der Wahrheit sein soll.

  4. Konflikt-Warnungen ignorieren. Wenn mehrere Sources dieselbe Variable liefern, warnt Hermes. Schalte die Warnung nicht einfach aus, sondern prüfe, welche Source gewinnen soll, oder nutze secrets.preserve_existing, um bestimmte Variablen in .env zu behalten.

  5. Interaktives Entsperren auf einem Server verwenden. op signin oder BW_SESSION-Sessions sind für Laptops okay, aber Cron, Gateway und CI sollten Service-Accounts oder Machine-Accounts mit nicht-interaktiven Tokens nutzen.

  6. example.env nicht aktualisieren. Sobald Secrets externalisiert sind, wird example.env zur einzigen Dokumentation der erwarteten Variablen. Halte sie mit der tatsächlichen Vault-Struktur synchron.

Kombination mit Smart Approvals

Keys aus .env zu entfernen, ist die statische Hälfte der Sicherheitsgeschichte. v0.19.0 aktiviert außerdem standardmäßig Smart Approvals: Wenn Hermes einen markierten Befehl ausführen möchte, bewertet ein unabhängiger LLM-Reviewer ihn, anstatt dich bei jedem einzelnen um Bestätigung zu bitten. Kombiniert mit dem externen Secret-Vault ergeben sich zwei Schutzschichten:

  • Statische Sicherheit: Secrets landen nicht im Klartext auf der Disk, verbreiten sich nicht über Maschinen und sind auditierbar.
  • Dynamische Sicherheit: Riskante Operationen bekommen eine zweite Meinung, sodass ein einzelner übergriffiger Tool-Call keinen Key exfiltrieren kann.

Zusammenfassung

SecretSource von Hermes v0.19.0 verschiebt das API-Key-Management von „Copy-Paste in .env“ zu „Beim Start aus externem Vault injizieren“. Fünf Schritte:

  1. Upgrade auf v0.19.0 und prüfe, dass hermes secrets verfügbar ist.
  2. Authentifiziere dich mit Bitwarden Secrets Manager oder 1Password und speichere das Bootstrap-Token in .env.
  3. Führe den Setup-Assistenten aus und konfiguriere die Source in config.yaml.
  4. Migriere die Keys aus .env in den Vault und behalte nur das Bootstrap-Token.
  5. Verifiziere mit status / sync, rotiere im Vault und halte einen Rollback-Pfad offen.

Deine .env kann sich von Dutzenden geheimen Zeilen auf ein einziges Bootstrap-Token reduzieren, während Hermes beim Start weiterhin alle benötigten Secrets bekommt. Teammembers brauchen keine geheimen Dateien mehr herumzuschicken, und Token-Rotation bedeutet nicht mehr, dutzende lokale Konfigurationen anfassen zu müssen.

Referenzen: