Configurer Hermes Agent en BYOK : guide pas à pas

Ce que BYOK signifie vraiment pour Hermes Agent

Hermes Agent est BYOK par défaut. Vous pointez l'agent vers n'importe quel fournisseur pour lequel vous avez déjà des identifiants, et chaque appel d'inférence est facturé à votre compte fournisseur, pas à une couche intermédiaire qui prend une marge sur les tokens. Ce n'est pas un contournement de paywall, c'est la posture par défaut de l'agent : agnostique au modèle, agnostique au fournisseur, et biaisée en faveur du backend auquel vous faites confiance pour vos données.

Deux choses embrouillent au début. Premièrement, le BYOK d'Hermes couvre les vraies clés API de LLM (OpenAI, Anthropic, OpenRouter, Kimi, MiniMax et beaucoup d'autres) et aussi les endpoints compatibles OpenAI, ce qui veut dire que vLLM ou Ollama auto-hébergés comptent aussi. Deuxièmement, le BYOK est par backend, pas tout-ou-rien. Vous pouvez utiliser Anthropic pour le raisonnement et Ollama pour des résumés d'arrière-plan à faible coût sur le même agent, si vous configurez les deux.

Le reste de ce guide couvre le choix du fournisseur, le stockage de la clé sans fuite, et le changement plus tard sans tout refaire.

Pourquoi le BYOK compte plus que des "crédits API gratuits"

Chaque SaaS d'IA finit par vous demander de faire confiance à sa clé mutualisée opaque. Le BYOK casse ce modèle. Votre identifiant, votre facture, votre politique de rétention des données, votre journal d'audit. Si la plateforme disparaît demain, votre compte fournisseur continue de tourner.

Les bénéfices concrets, dans l'ordre où ils comptent le plus dans de vrais déploiements Hermes :

Contrôle des données. Les journaux côté fournisseur, les règles de rétention et les clauses Zero Data Retention sont régis par votre contrat avec le fournisseur du modèle, pas par les défauts négociés par l'éditeur de l'agent.
Transparence du coût. Aucune marge cachée entre vous et le modèle. Avec OpenRouter, vous voyez le même coût par token qu'avec un curl direct.
Pas de lock-in fournisseur. Changer de fournisseur se fait en deux lignes de config, pas en projet de migration. La commande hermes model bascule entre Claude, GPT, Gemini ou Llama sans toucher aux skills ni à la mémoire.
Bouton d'arrêt de votre côté. Si une clé fuite ou si la facture s'emballe, vous la faites tourner depuis le tableau de bord du fournisseur. L'agent s'arrête en quelques secondes et personne d'autre n'a besoin de valider la rotation.

Pour le plan Starter d'Hermify, le BYOK est tout l'intérêt. La formule est pensée autour de "vous apportez la clé, on fait tourner le conteneur". C'est pourquoi la configuration ci-dessous vaut la peine d'être apprise même si vous prévoyez de passer à l'hébergement managé plus tard.

Pas à pas : configurer votre premier fournisseur BYOK

Hermes a besoin d'au moins un fournisseur configuré pour démarrer. Le chemin le moins friction est OpenRouter (une clé, des centaines de modèles), mais la mécanique est la même pour OpenAI, Anthropic et tous les autres backends supportés.

1. Récupérez une clé chez le fournisseur

Choisissez-en un et générez une clé depuis son tableau de bord :

OpenRouter sur openrouter.ai. La clé commence par sk-or-. Meilleur choix par défaut pour le BYOK.
OpenAI sur platform.openai.com. La clé commence par sk-.
Anthropic sur console.anthropic.com. La clé commence par sk-ant-.
Kimi, MiniMax, GLM, Nous Portal et d'autres suivent le même schéma : inscription, génération d'une clé, copie unique.
Ollama ou vLLM en local sur votre machine. Pas besoin de clé, juste l'URL de l'endpoint compatible OpenAI.

Ajoutez du crédit (ou un moyen de paiement) chez le fournisseur. Si le compte est à zéro, Hermes échouera au premier appel d'inférence avec une erreur claire.

2. Lancez la configuration interactive

Depuis le terminal, sur la machine où vit Hermes :

hermes setup

Choisissez votre fournisseur dans la liste, collez la clé, et sélectionnez un modèle. Hermes écrit la configuration pour vous.

Si vous préférez scripter, la même chose sans prompts :

hermes config set OPENROUTER_API_KEY sk-or-votre-cle-ici
hermes config set MODEL "anthropic/claude-sonnet-latest"

Le préfixe ~ dans un identifiant de modèle (~anthropic/claude-sonnet-latest) signifie "dernière version de cette famille", donc vous n'avez pas à courir après les nouveaux snapshots à la main.

3. Sachez où vit la clé

Hermes stocke secrets et configuration dans des fichiers séparés, à dessein :

Les secrets vont dans ~/.hermes/.env (permission 600, seul l'utilisateur peut le lire).
Le nom du fournisseur, le modèle et les feature flags vont dans ~/.hermes/config.yaml et peuvent être versionnés sans risque.

Cette séparation compte. Vous pouvez versionner config.yaml dans un repo privé ou dans vos dotfiles et reproduire une installation Hermes sur une autre machine, puis y ajouter la clé depuis une variable d'environnement ou un gestionnaire de secrets sans jamais l'écrire en clair sur le disque.

Si vous versionnez la configuration, ajoutez ~/.hermes/.env à votre .gitignore. Si vous utilisez un gestionnaire de secrets (1Password CLI, doppler, sops, Bitwarden), vous pouvez générer le .env au boot au lieu de laisser la clé sur le disque en permanence.

4. Vérifiez que ça marche

Envoyez un test de fumée via Hermes :

hermes chat "dis bonjour et dis-moi quel modèle tu es"

Si la clé est fausse, si le compte n'a plus de crédit ou si l'endpoint est injoignable, l'erreur vous dira lequel. Corrigez et relancez. Ne passez pas aux skills, aux tâches planifiées ou au réglage de la mémoire tant que le fournisseur ne répond pas proprement.

Choisir le bon fournisseur pour votre setup

Vous n'êtes pas verrouillé sur votre premier choix. Mais le premier compte, parce qu'il fixe le plafond du travail de mémoire, d'appel d'outils et de contexte long qu'Hermes va tenter.

Vous voulez zéro friction, "juste que ça marche" : OpenRouter avec ~anthropic/claude-sonnet-latest. Une clé, une facture, changements de modèle faciles.
Vous avez déjà un compte OpenAI ou Anthropic : utilisez le fournisseur direct. Coût par token légèrement inférieur au routage via OpenRouter, mais sans fallback entre fournisseurs.
Vous voulez rester sur l'infrastructure Nous Research : Nous Portal est le chemin officiellement béni et s'accorde naturellement avec les system prompts d'Hermes.
Vous voulez tourner en local : Ollama ou vLLM comme endpoint compatible OpenAI. Zéro coût par token, il faut une machine avec GPU, et un modèle qui supporte vraiment les tool calls pour être utile à l'agent.
Vous voulez une isolation stricte des données : Anthropic en direct (Zero Data Retention sur demande) ou un endpoint auto-hébergé. Ne passez pas par un agrégateur si c'est votre priorité.

Hermes a besoin d'un modèle avec au moins 64K tokens de contexte, parce que les fichiers de mémoire persistante (MEMORY.md, USER.md, skills) sont injectés à chaque appel. Les modèles à petit contexte tronquent silencieusement le contexte, ce qui casse la boucle mémoire qui distingue Hermes d'un chatbot sans état.

Pour aller plus loin sur le choix du modèle lui-même, voyez comment configurer Hermes Agent avec OpenRouter.

Erreurs de configuration à éviter

Quelques patterns coincent les utilisateurs sur leur premier setup BYOK :

Commiter le fichier .env. L'erreur la plus courante. Même un dépôt GitHub "privé" n'est pas un endroit sûr pour des clés sk-. Ajoutez .env à .gitignore dès le premier jour.
Choisir un modèle sans support des tool calls. Certains modèles bon marché sur OpenRouter ne savent pas appeler d'outils. Hermes en a besoin pour l'écriture de fichiers, les fetches web, les tâches planifiées et MCP. Si les skills tombent en panne silencieusement, vérifiez les capacités du modèle.
Sous-approvisionner le compte fournisseur. Les fournisseurs mettent les requêtes en pause quand le crédit passe sous un seuil. Configurez un rechargement automatique sur OpenRouter ou une alerte de solde bas sur OpenAI, pour qu'un long cron Hermes ne meure pas à 3h du matin.
Stocker la clé dans l'historique du shell. hermes config set OPENROUTER_API_KEY sk-or-... s'écrit dans .bash_history par défaut. Préférez hermes setup (interactif, pas d'historique), ou préfixez la commande par un espace si votre shell est configuré pour ignorer ces lignes.
Supposer qu'une seule clé couvre tout. Les outils MCP qui ont besoin de leurs propres identifiants (un token GitHub, une clé Notion) sont des slots BYOK distincts. La clé LLM ne les débloque pas.
Ne pas rotationner. Mettez un rappel calendrier tous les 90 jours pour rotationner la clé fournisseur. hermes config set écrase l'ancienne valeur proprement.

Si vous êtes bloqué, le troubleshooting d'Hermes Agent sur Telegram couvre les modes de défaillance courants de bout en bout.

Ce qui change avec l'hébergement managé

Tout ce qui précède décrit une installation Hermes auto-hébergée. Si vous déployez via Hermify, le modèle BYOK est identique (votre clé, votre facture, vos données), mais la mécanique passe dans un tableau de bord :

Collez la clé OpenRouter, OpenAI ou Anthropic une fois dans l'onboarding.
Hermify la chiffre au repos et l'injecte dans votre conteneur au démarrage. Elle n'apparaît jamais dans les logs, n'est jamais réaffichée après enregistrement, et se rotationne proprement à la demande.
Changez de modèle depuis le tableau de bord sans faire de SSH nulle part. Le changement prend effet au prochain redémarrage de l'agent, à un clic de distance.
Le plan Starter est BYOK-only par conception. Pro et Dedicated incluent une clé managée si vous préférez sauter l'inscription chez le fournisseur, mais vous pouvez tout de même apporter la vôtre si vous le souhaitez.

L'idée, c'est que le BYOK n'est pas une caractéristique réservée au self-hosting. C'est une posture : votre identifiant, vos données, votre bouton d'arrêt. L'hébergement managé la préserve, il s'occupe simplement de l'opérationnel autour.

Commencez

Si vous êtes en auto-hébergement, lancez hermes setup, collez la clé, terminé. Si vous voulez le même modèle BYOK sans la maintenance du conteneur, commencez avec Hermify et vous êtes en ligne sur Telegram en une minute environ.

Dans les deux cas, gardez la clé de votre côté de la barrière. C'est à ça que sert le BYOK.