Last updated on

Arrête de bourrer tes API keys dans .env : intègre le nouveau coffre-fort externe de Hermes v0.19 en 5 étapes

Combien de clés API traînent actuellement dans ton fichier ~/.hermes/.env ? OpenAI, Anthropic, GitHub, Telegram, Discord, Cloudflare, AWS — à chaque nouvelle intégration, tu colles une nouvelle ligne SOME_KEY=sk-.... Puis tu vérifies trois fois .gitignore avant de commit, tu t’envoies le fichier par Slack en changeant de machine, et tu le recopies dans les secrets CI. Pire, chaque membre de l’équipe garde une copie locale, donc personne ne sait quelle version est la bonne, qui a changé quoi, ou si une clé a fuité.

Hermes Agent v0.19.0 transforme ce bazar en une abstraction propre : SecretSource. Il permet à Hermes de lire les clés API depuis un coffre-fort externe au démarrage, avec un support natif pour Bitwarden Secrets Manager et 1Password. Tu gardes un seul token d’amorçage dans .env et tu laisses le vault gérer le reste. Les clés n’ont plus besoin de vivre en clair dans .env.

Cet article te propose une migration pratique en 5 étapes. Pas besoin de tout refactorer d’un coup — tu peux d’abord déplacer les clés les plus sensibles tout en gardant un chemin de rollback ouvert.

Pour le récapitulatif complet de la v0.19.0, consulte nos notes de version v0.19.0 et le guide des combos de skills.

Pourquoi .env n’est pas une solution pérenne

.env est parfait pour les prototypes, mais il montre ses limites dès que Hermes se connecte à une douzaine d’outils et de services :

  1. Risque de propagation. À chaque fois que tu copies .env sur une autre machine, un conteneur ou un environnement CI, tu crées une nouvelle surface d’attaque. GitHub détecte chaque année des millions de secrets commités accidentellement.
  2. Pas d’audit. .env ne te dit pas qui a changé quelle clé, ni quand. Une clé peut être rotatée et le reste de l’équipe ne s’en aperçoit que quand quelque chose tombe en panne.
  3. Rotation douloureuse. Une rotation trimestrielle des tokens signifie modifier N fichiers et N points d’injection de variables d’environnement, puis espérer qu’on n’a rien oublié.

Un coffre-fort externe ne se contente pas de « cacher du texte en clair » : il transforme les secrets en ressources contrôlées, auditables et centralisées. SecretSource de Hermes v0.19.0 connecte cette idée directement au chemin de démarrage de l’agent, qui lit alors les valeurs du vault comme de simples variables d’environnement.

Ce que SecretSource de Hermes v0.19.0 peut faire

Selon les notes de version v0.19.0 et la documentation officielle Secrets, l’interface SecretSource offre :

  • Plusieurs vaults à la fois. Bitwarden Secrets Manager et 1Password peuvent être activés simultanément. Une source générique command permet aussi d’adapter n’importe quel vault qui imprime des lignes KEY=VALUE.
  • Précédence déterministe. Hermes résout les conflits selon une règle claire : les mappages env: explicites (1Password, command source) battent les pulls massifs de projet (Bitwarden) ; au sein du même type, l’ordre de la liste optionnelle secrets.sources décide ; les valeurs .env et shell l’emportent par défaut, sauf si une source a override_existing: true.
  • Avertissements de conflit. Si une source ultérieure fournit aussi une variable déjà revendiquée par une source antérieure, Hermes avertit au lieu de choisir silencieusement.
  • Traçabilité des variables. Chaque variable injectée mémorise la source qui l’a fournie — visible dans les logs de démarrage et la commande status.
  • Démarrage non bloquant. Si le vault est inaccessible ou si l’authentification échoue, Hermes affiche un avertissement d’une ligne avec la prochaine action recommandée, puis continue avec les credentials déjà présents dans .env.

Cela signifie que tu peux écrire une configuration comme celle-ci sans mettre OPENAI_API_KEY dans .env du tout :

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

Les cinq sections suivantes montrent comment rendre cela concret.

Étape 1 : Passer à Hermes v0.19.0 et vérifier la CLI

SecretSource est une fonctionnalité de la v0.19.0, donc commence par vérifier la version :

hermes --version

Puis confirme que la sous-commande secrets existe :

hermes secrets --help

Tu devrais voir bitwarden, onepassword et d’autres helpers. Si tu es en dessous de la v0.19.0, lance le script d’installation :

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

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

Étape 2 : Choisir un vault et s’authentifier

Hermes ne gère pas l’authentification à ta place ; il s’appuie sur le flux officiel de chaque vault. Tu dois configurer cela sur la machine où Hermes s’exécute.

Option A : Bitwarden Secrets Manager

Tu as besoin d’un compte machine dans Bitwarden Secrets Manager, pas du vault de mots de passe grand public. Le compte machine est conçu pour les charges de travail non interactives.

  1. Dans la web app Bitwarden, passe à Secrets Manager.
  2. Crée un Project (par exemple Hermes keys).
  3. Ajoute tes provider keys en tant que secrets. Le Nom du secret devient le nom de la variable d’environnement attendue par Hermes — OPENAI_API_KEY, ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN, etc.
  4. Va dans Machine accounts → New machine account et accorde-lui un accès en lecture au projet.
  5. Sous Access tokens, crée un token (commence par 0., impossible à réafficher ensuite) et copie-le.

Stocke ce token dans ~/.hermes/.env sous BWS_ACCESS_TOKEN :

BWS_ACCESS_TOKEN=0.xxx...

La binaire bws est téléchargée automatiquement dans ~/.hermes/bin/ au premier besoin — pas besoin de brew, apt ni sudo.

Option B : 1Password

Installe le CLI officiel 1Password (op) et vérifie qu’il fonctionne :

op --version
op whoami

Ordinateur portable / interactif : connecte-toi avec op signin ou active l’intégration CLI dans l’application 1Password. Hermes transmettra tes variables de session au sous-processus op.

Serveur / CI / cron : crée un service account, accorde-lui un accès en lecture au vault concerné, puis stocke le token dans ~/.hermes/.env :

OP_SERVICE_ACCOUNT_TOKEN=ops_...

Note de sécurité : Le token d’amorçage (BWS_ACCESS_TOKEN ou OP_SERVICE_ACCOUNT_TOKEN) est lui-même un credential de grande valeur. Garde .env hors du contrôle de version et restreins les permissions du fichier.

Étape 3 : Lancer l’assistant de configuration et configurer la source

Hermes fournit une CLI dédiée pour chaque source. L’assistant écrit dans ~/.hermes/config.yaml (ou ~/.hermes/profiles/<profile>/config.yaml si tu utilises un profil nommé).

Bitwarden

Lance l’assistant interactivement :

hermes secrets bitwarden setup

Ou en mode non interactif :

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

La configuration résultante ressemble à ceci :

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

Lance l’assistant :

hermes secrets onepassword setup

Ou avec un service-account token :

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

Puis mappe chaque variable d’environnement à une référence op:// :

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"

La configuration résultante :

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

Utiliser les deux sources ensemble

Tu peux activer les deux simultanément. Contrôle l’ordre avec la liste sources :

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

N’oublie pas que les sources avec mappages explicites (1Password) ont automatiquement la priorité sur les sources massives (Bitwarden), indépendamment de l’ordre. Au sein du même type, la première source gagne.

Étape 4 : Migrer les clés API en clair vers le vault

4.1 Inventorier les clés de .env

Liste les secrets actuellement utilisés par Hermes, regroupés par impact :

  • Clés API de modèles : OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.
  • Tokens de plateformes : TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN
  • Credentials cloud : AWS_ACCESS_KEY_ID, CLOUDFLARE_API_TOKEN, GCP_API_KEY
  • Outils tiers : GitHub PATs, Sentry DSNs, clés Stripe, etc.

4.2 Créer les secrets dans le vault

Bitwarden : dans le projet sélectionné, crée un secret par variable d’environnement. Le nom doit correspondre exactement à celui attendu par Hermes, par exemple OPENAI_API_KEY. Lorsque tu lances hermes secrets bitwarden sync, Hermes liste les variables qu’il peut résoudre.

1Password : crée les items et champs correspondant à tes références op://vault/item/field. Par exemple, si tu as mappé OPENAI_API_KEY vers op://Private/OpenAI/api key, tu dois créer un item nommé OpenAI dans le vault Private avec un champ api key.

Ordre de migration suggéré : déplace d’abord les clés à fort impact (Stripe, équivalents root AWS, clés principales des fournisseurs de modèles), puis les clés read-only à faible risque.

4.3 Réduire .env et créer un example.env

Une fois qu’une clé vit dans le vault, supprime-la ou commente-la dans .env. Ne garde que le token d’amorçage nécessaire à la source :

# ~/.hermes/.env
BWS_ACCESS_TOKEN=0.xxx...
# ou pour 1Password :
# OP_SERVICE_ACCOUNT_TOKEN=ops_...

Crée ensuite un example.env avec les noms de variables et des commentaires, mais sans valeurs réelles :

# example.env — les vraies valeurs sont dans le vault externe
OPENAI_API_KEY=see-vault
ANTHROPIC_API_KEY=see-vault
TELEGRAM_BOT_TOKEN=see-vault

Les nouveaux membres de l’équipe savent ainsi quelles variables sont attendues et quel vault consulter, sans que personne ne leur envoie un vrai .env.

Étape 5 : Vérifier, faire tourner et garder un chemin de rollback

5.1 Vérifier que l’intégration est active

Bitwarden :

hermes secrets bitwarden status
hermes secrets bitwarden sync        # dry-run : aperçu de ce qui serait appliqué
hermes secrets bitwarden sync --apply  # exporte dans le shell actuel

1Password :

hermes secrets onepassword status
hermes secrets onepassword sync        # dry-run
hermes secrets onepassword sync --apply  # exporte dans le shell actuel

Démarre un nouveau processus Hermes (ou un cron job, ou le service gateway) pour qu’il récupère les valeurs résolues. Tu peux confirmer la provenance dans le log de démarrage ou dans la commande status de la source.

5.2 Configurer des rappels de rotation

La plupart des vaults permettent d’ajouter un champ ou une note avec la date de rotation. Configure un rappel de 90 jours dans ton calendrier. Quand une clé de provider change, mets-la à jour uniquement dans le vault — rien d’autre. Le prochain démarrage de Hermes utilisera automatiquement la nouvelle valeur.

Si le token d’amorçage lui-même fuite ou expire, fais-le tourner sans relancer l’assistant complet :

hermes secrets bitwarden token
hermes secrets onepassword token

Ces deux commandes vérifient le token avant de l’écrire, donc une mauvaise copie ne casse pas la configuration actuelle.

5.3 Garder un chemin de rollback

Ne retire pas toutes les clés d’un coup. Une séquence plus sûre :

  1. Migration canari : déplace une clé non critique (par exemple une API de recherche en lecture seule) dans le vault et vérifie.
  2. Observation en double écriture : garde le vault et .env peuplés, mais active override_existing: true sur la source. Observe quelques jours.
  3. Nettoyage propre : une fois stable, supprime les vraies clés correspondantes de .env et ne garde que le token d’amorçage.

Si quelque chose casse, le rollback le plus rapide est de désactiver la source :

hermes secrets bitwarden disable
hermes secrets onepassword disable

Hermes revient immédiatement à n’utiliser que les credentials de .env.

Pièges courants

  1. Mettre de vrais secrets dans config.yaml. config.yaml ne doit contenir que des références (op://...) et des IDs de projet. Les vraies valeurs doivent rester dans le vault.

  2. Stocker le token d’amorçage du vault dans un .env partagé et le commiter. BWS_ACCESS_TOKEN et OP_SERVICE_ACCOUNT_TOKEN sont des tokens de grande valeur. Garde .env hors du contrôle de version et restreins les permissions du fichier.

  3. Penser que .env perd automatiquement la priorité. Par défaut, .env et les exports shell l’emportent. Si une source a override_existing: false et que d’anciennes clés restent dans .env, Hermes continue à utiliser les valeurs de .env. Règle override_existing: true quand le vault doit être la source de vérité.

  4. Ignorer les avertissements de conflit. Quand plusieurs sources fournissent la même variable, Hermes avertit. Ne désactive pas l’avertissement tant que tu n’as pas confirmé quelle source doit gagner, ou utilise secrets.preserve_existing pour garder certaines variables dans .env.

  5. Utiliser un déverrouillage interactif sur un serveur. op signin ou les sessions BW_SESSION vont bien pour les ordinateurs portables, mais cron, gateway et CI devraient utiliser des service accounts ou comptes machines avec des tokens non interactifs.

  6. Oublier de mettre à jour example.env. Une fois les secrets externalisés, example.env devient la seule documentation des variables attendues. Garde-le synchronisé avec la structure réelle du vault.

Le combiner avec des approbations plus intelligentes

Sortir les clés de .env est la moitié statique de l’histoire de sécurité. La v0.19.0 active aussi par défaut les Smart Approvals : quand Hermes veut exécuter une commande marquée, un reviewer LLM indépendant l’évalue au lieu de te demander d’approuver chaque action. Combiné au coffre-fort externe, cela donne deux couches de protection :

  • Sécurité statique : les secrets n’atterrissent pas en clair sur le disque, ne se propagent pas entre les machines et sont auditables.
  • Sécurité dynamique : les opérations risquées reçoivent un second avis, donc un seul appel d’outil outrepassant ne peut pas exfiltrer une clé.

Résumé

SecretSource de Hermes v0.19.0 déplace la gestion des clés API de « copier-coller dans .env » à « injecter depuis un vault externe au démarrage ». Cinq étapes :

  1. Mets à jour vers la v0.19.0 et confirme que hermes secrets existe.
  2. Authentifie-toi avec Bitwarden Secrets Manager ou 1Password, et stocke le token d’amorçage dans .env.
  3. Lance l’assistant et configure la source dans config.yaml.
  4. Migre les clés de .env vers le vault, en ne gardant que le token d’amorçage.
  5. Vérifie avec status / sync, fais tourner les clés côté vault et garde un chemin de rollback.

Ton .env peut passer de dizaines de lignes de secrets à un seul token d’amorçage, tandis que Hermes continue d’obtenir chaque secret dont il a besoin au démarrage. L’onboarding des nouveaux membres n’implique plus d’envoyer des fichiers secrets, et la rotation des tokens ne signifie plus de fouiller dans une douzaine de configurations locales.

Références :