Menu

Configurer Hermes Agent proprement

Configurer Hermes Agent proprement

Cette page fait partie du guide pratique francophone consacré à Hermes Agent. Elle répond à l'intention de recherche : configurer modèle, providers et options.

Le contenu s'appuie sur la documentation officielle Hermes Agent associée à cette page. L'objectif n'est pas de remplacer la documentation de Nous Research, mais de fournir une lecture claire en français, structurée pour aller vite, avec un maillage logique vers les pages complémentaires du même site.

À retenir

  • Sujet principal : configurer hermes agent.
  • Type de page : spoke.
  • Cluster : guides.
  • Source canonique : documentation officielle Hermes Agent.
  • Aucun lien vers l'autre domaine n'est utilisé dans cette page.

Quand utiliser cette page

Utilisez cette page quand vous voulez configurer modèle, providers et options. Elle part du principe que Hermes Agent est déjà identifié comme l'outil à mettre en place ou à comprendre, puis détaille les points importants issus de la documentation officielle.

Si vous découvrez seulement l'outil, revenez d'abord au hub parent puis suivez les liens internes proposés en fin de page.

Base officielle

All settings are stored in the ~/.hermes/ directory for easy access.

Run hermes setup --portal — one OAuth gets you a model provider and all four Tool Gateway tools without hand-editing YAML. Portal subscribers also get 10% off token-billed providers. See Nous Portal.

Directory Structure

~/.hermes/
├── config.yaml     # Settings (model, terminal, TTS, compression, etc.)
├── .env            # API keys and secrets
├── auth.json       # OAuth provider credentials (Nous Portal, etc.)
├── SOUL.md         # Primary agent identity (slot #1 in system prompt)
├── memories/       # Persistent memory (MEMORY.md, USER.md)
├── skills/         # Agent-created skills (managed via skill_manage tool)
├── cron/           # Scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # Logs (errors.log, gateway.log — secrets auto-redacted)

Managing Configuration

hermes config              # View current configuration
hermes config edit         # Open config.yaml in your editor
hermes config set KEY VAL  # Set a specific value
hermes config check        # Check for missing options (after updates)
hermes config migrate      # Interactively add missing options

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...  # Saves to .env

The hermes config set command automatically routes values to the right file — API keys are saved to .env, everything else to config.yaml.

Configuration Precedence

Settings are resolved in this order (highest priority first):

  1. CLI arguments — e.g., hermes chat --model anthropic/claude-sonnet-4 (per-invocation override)
  2. ~/.hermes/config.yaml — the primary config file for all non-secret settings
  3. ~/.hermes/.env — fallback for env vars; required for secrets (API keys, tokens, passwords)
  4. Built-in defaults — hardcoded safe defaults when nothing else is set

Secrets (API keys, bot tokens, passwords) go in .env. Everything else (model, terminal backend, compression settings, memory limits, toolsets) goes in config.yaml. When both are set, config.yaml wins for non-secret settings.

An administrator can pin specific config and secret values that a standard user

cannot override, via a system-level managed directory. See

Managed Scope.

Environment Variable Substitution

You can reference environment variables in config.yaml using ${VAR_NAME} syntax:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

Multiple references in a single value work: url: "${HOST}:${PORT}". If a referenced variable is not set, the placeholder is kept verbatim (${UNDEFINED_VAR} stays as-is). Only the ${VAR} syntax is supported — bare $VAR is not expanded.

For AI provider setup (OpenRouter, Anthropic, Copilot, custom endpoints, self-hosted LLMs, fallback models, etc.), see AI Providers.

Provider Timeouts

You can set providers.<id>.request_timeout_seconds for a provider-wide request timeout, plus providers.<id>.models.<model>.timeout_seconds for a model-specific override. Applies to the primary turn client on every transport (OpenAI-wire, native Anthropic, Anthropic-compatible), the fallback chain, rebuilds after credential rotation, and (for OpenAI-wire) the per-request timeout kwarg — so the configured value wins over the legacy HERMES_API_TIMEOUT env var.

You can also set providers.<id>.stale_timeout_seconds for the non-streaming stale-call detector, plus providers.<id>.models.<model>.stale_timeout_seconds for a model-specific override. This wins over the legacy HERMES_API_CALL_STALE_TIMEOUT env var.

Leaving these unset keeps the legacy defaults (HERMES_API_TIMEOUT=1800s, HERMES_API_CALL_STALE_TIMEOUT=90s, native Anthropic 900s). The non-streaming stale detector is auto-disabled for local endpoints when left implicit and can scale upward for very large contexts. Not currently wired for AWS Bedrock (both bedrock_converse and AnthropicBedrock SDK paths use boto3 with its own timeout configuration). See the commented example in cli-config.yaml.example.

Update Behavior

hermes update settings live under updates in config.yaml:

updates:
  pre_update_backup: false       # Create a full HERMES_HOME zip before every update
  backup_keep: 5                 # Keep this many pre-update backup zips
  non_interactive_local_changes: stash  # stash | discard

For git installs, Hermes auto-stashes dirty tracked files and untracked files before checking out the update branch or pulling. Interactive terminal updates prompt before restoring that stash. Non-interactive updates (desktop/chat app, gateway, or --yes) use updates.non_interactive_local_changes: stash restores local source edits after a successful pull, while discard drops the update-created stash after a successful pull. Use discard only on managed installs where local source edits are never meant to persist.

Before that stash step, Hermes also restores tracked package-lock.json diffs left by npm install/build churn. Commit or manually stash intentional lockfile edits before updating.

Terminal Backend Configuration

Hermes supports six terminal backends. Each determines where the agent's shell commands actually execute — your local machine, a Docker container, a remote server via SSH, a Modal cloud sandbox (direct or via the Nous-managed gateway), a Daytona workspace, or a Singularity/Apptainer container.

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # Gateway/cron working directory (CLI always uses launch dir)
  timeout: 180      # Per-command timeout in seconds
  home_mode: auto   # auto | real | profile — subprocess HOME policy
  env_passthrough: []  # Env var names to forward to sandboxed execution (terminal + execute_code)
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Container image for Singularity backend
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Container image for Modal backend
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Container image for Daytona backend

For cloud sandboxes such as Modal and Daytona, container_persistent: true means Hermes will try to preserve filesystem state across sandbox recreation. It does not promise that the same live sandbox, PID space, or background processes will still be running later.

Backend Overview

  • Backend — Where commands run — Isolation — Best for
  • local — Your machine directly — None — Development, personal use
  • docker — Single persistent Docker container (shared across session, /new, subagents) — Full (namespaces, cap-drop) — Safe sandboxing, CI/CD
  • ssh — Remote server via SSH — Network boundary — Remote dev, powerful hardware
  • modal — Modal cloud sandbox — Full (cloud VM) — Ephemeral cloud compute, evals
  • daytona — Daytona workspace — Full (cloud container) — Managed cloud dev environments
  • singularity — Singularity/Apptainer container — Namespaces (--containall) — HPC clusters, shared machines

Local Backend

The default. Commands run directly on your machine with no isolation. No special setup required.

terminal:
  backend: local

By default, local tool subprocesses keep your real OS-user HOME. This lets

external CLIs such as git, ssh, gh, az, npm, Claude Code, and Codex

find the credentials and config they already use in your normal shell. Hermes

state is still profile-scoped through HERMES_HOME; HOME is not how profiles

select config, memory, sessions, or skills.

Hermes does not change your system-wide HOME, your shell startup files, or

the operating system account home. This setting only controls the environment

passed to subprocesses that Hermes launches through tools such as terminal,

background terminal processes, execute_code, and ACP helper processes.

terminal.home_mode

  • Mode — Host installs — Containers — Tradeoff
  • auto — Keep the real OS-user HOME — Use {HERMES_HOME}/home — Recommended default. Host CLIs keep working; container state persists.
  • real — Force the real OS-user HOME — Force the real OS-user HOME if visible — Useful if a parent process accidentally started with HOME pointed at a profile home.
  • profile — Use {HERMES_HOME}/home when it exists — Use {HERMES_HOME}/home when it exists — Strict per-profile CLI config isolation, but normal ~/.ssh, ~/.gitconfig, ~/.azure, ~/.config/gh, Claude/Codex auth, npm state, etc. will not be visible unless you initialize or link them inside the profi

Points de vigilance

  • Vérifiez toujours la version active de Hermes Agent avant d'appliquer une commande ou une configuration.
  • Ne collez pas de clé API dans un chat public ou dans une page visible.
  • Gardez les secrets dans les fichiers ou gestionnaires prévus pour cela.
  • Si une fonctionnalité dépend d'un provider, d'un plugin ou d'une plateforme de messagerie, vérifiez que le composant est bien activé dans votre profil.
  • Pour une installation de production, testez d'abord le flux complet sur une machine ou un profil isolé.

Exemple de parcours logique

  1. Lire la page courante pour comprendre configurer hermes agent.
  2. Ouvrir le hub parent du cluster guides.
  3. Passer ensuite aux pages complémentaires proposées dans « À lire ensuite ».
  4. Revenir à la documentation officielle si vous avez besoin du détail exact ou d'une commande récemment modifiée.

FAQ rapide

Cette page remplace-t-elle la documentation officielle ?

Non. Elle sert de guide francophone structuré. Le lien vers la source officielle est disponible en bas de page.

Les commandes sont-elles garanties à jour ?

Elles sont basées sur la documentation officielle récupérée au moment de la génération. Pour un usage critique, vérifiez toujours la page officielle liée en bas.

Pourquoi autant de liens internes ?

Hermes Agent est un système modulaire. L'installation, les providers, les outils, la mémoire, les skills, la sécurité et les plateformes se répondent. Le maillage interne aide à suivre ce chemin sans tomber sur des pages orphelines.

Comment lire cette page efficacement

Commencez par identifier votre situation : installation locale, usage serveur, configuration d'un provider, connexion à une plateforme, automatisation ou usage développeur. Hermes Agent est modulaire : une fonctionnalité dépend souvent d'un autre bloc. Par exemple, une automatisation cron devient réellement utile quand le modèle, les outils et le canal de livraison sont déjà configurés.

Pour éviter les erreurs, avancez toujours dans cet ordre : vérifier le prérequis, appliquer la commande ou la configuration, relancer une session si nécessaire, puis tester avec une action simple. Si le résultat ne correspond pas à ce qui est attendu, revenez à la page officielle liée en bas et comparez la version de votre installation avec la documentation actuelle.

Bonnes pratiques

  • Garder une configuration minimale tant que le premier test n'est pas validé.
  • Ajouter les outils et plateformes progressivement.
  • Séparer les profils si plusieurs usages doivent cohabiter.
  • Documenter les procédures répétées dans des skills plutôt que dans de longs prompts.
  • Vérifier les droits, tokens et scopes avant d'accuser le modèle ou Hermes Agent.
  • Relancer la session après un changement de configuration important.

Erreurs fréquentes

La première erreur consiste à activer trop de choses trop tôt. Plus la configuration initiale est large, plus le diagnostic devient difficile. La deuxième erreur consiste à confondre un problème de provider avec un problème Hermes : si le modèle ne répond pas, vérifiez d'abord l'authentification, la clé API, le nom du modèle et le provider sélectionné. La troisième erreur consiste à oublier que certains changements ne s'appliquent qu'à une nouvelle session ou après redémarrage du gateway.

Suite recommandée

Après cette page, ouvrez les liens internes proposés dans la section « À lire ensuite ». Ils ont été choisis pour suivre une progression logique dans le même site, sans envoyer vers l'autre domaine.

À lire ensuite