Utiliser Hermes Agent avec Docker

Cette page fait partie du guide pratique francophone consacré à Hermes Agent. Elle répond à l'intention de recherche : comprendre installation ou backend Docker.

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 : hermes agent docker.
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 comprendre installation ou backend Docker. 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

There are two distinct ways Docker intersects with Hermes Agent:

Running Hermes IN Docker — the agent itself runs inside a container (this page's primary focus)
Docker as a terminal backend — the agent runs on your host but executes every command inside a single, persistent Docker sandbox container that survives across tool calls, /new, and subagents for the life of the Hermes process (see Configuration → Docker Backend)

This page covers option 1. The container stores all user data (config, API keys, sessions, skills, memories) in a single directory mounted from the host at /opt/data. The image itself is stateless and can be upgraded by pulling a new version without losing any configuration.

Quick start

If this is your first time running Hermes Agent, create a data directory on the host and start the container interactively to run the setup wizard:

Some VPS providers (Hetzner Cloud, and several others) offer a browser-based

console for managing hosts. These consoles transmit special characters

incorrectly — : may arrive as ;, @ may be mis-rendered, and non-English

keyboard layouts fare worse — which silently corrupts docker run arguments

like -v ~/.hermes:/opt/data, -e KEY=value, and pasted API keys / tokens.

Connect over SSH instead (ssh root@<host>) for copy-paste-safe command

entry. If you must use the browser console, type the commands manually

instead of pasting, and double-check every :, @, =, and / in the

result before hitting Enter.

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

This drops you into the setup wizard, which will prompt you for your API keys and write them to ~/.hermes/.env. You only need to do this once. It is highly recommended to set up a chat system for the gateway to work with at this point.

Inside the container, run hermes setup --portal once — the refresh token persists in the mounted ~/.hermes volume. See Nous Portal.

Running in gateway mode

Once configured, run the container in the background as a persistent gateway (Telegram, Discord, Slack, WhatsApp, etc.):

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Port 8642 exposes the gateway's OpenAI-compatible API server and health endpoint. It's optional if you only use chat platforms (Telegram, Discord, etc.), but required if you want the dashboard or external tools to reach the gateway.

Inside the official Docker image, gateway run is automatically supervised by s6-overlay: if the gateway process crashes it's restarted within a couple of seconds without losing the container, and the dashboard (when HERMES_DASHBOARD=1 is set) is supervised alongside it. The gateway run CMD process itself is a sleep infinity heartbeat that keeps the container alive while s6 manages the actual gateway process — so docker stop still shuts everything down cleanly, but docker logs shows the supervised gateway's output.

You'll see a one-line breadcrumb in docker logs confirming the upgrade. To opt out — and get the historical "gateway is the container's main process, container exit = gateway exit" semantics — pass --no-supervise or set HERMES_GATEWAY_NO_SUPERVISE=1. The opt-out is useful for CI smoke tests that want the container to exit with the gateway's status code; for production deployments the supervised default is strictly better.

This behavior applies to the s6-based image only. Earlier (tini-based) images still run gateway run as the foreground main process.

See the Where the logs go section below for the full routing map (per-profile gateways, dashboard, boot reconciler, container-wide docker logs).

The tool_loop_guardrails.hard_stop_enabled setting defaults to false, which is reasonable for interactive CLI and TUI sessions where a person can see repeated tool-call warnings. In unattended gateway or server deployments, warnings alone may not stop an agent that gets stuck in a repeated tool-call loop. Operators who want circuit-breaker behavior should explicitly enable hard stops in the profile's config.yaml:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

Note: the API server is gated on API_SERVER_ENABLED=true. To expose it beyond 127.0.0.1 inside the container, also set API_SERVER_HOST=0.0.0.0 and an API_SERVER_KEY (minimum 8 characters — generate one with openssl rand -hex 32). Example:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

Opening any port on an internet facing machine is a security risk. You should not do it unless you understand the risks.

Running the dashboard

The built-in web dashboard runs as a supervised s6-rc service alongside the gateway in the same container. Set HERMES_DASHBOARD=1 to bring it up:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

The dashboard is supervised by s6 — if it crashes, s6-supervise restarts it automatically after a short backoff. Dashboard stdout/stderr is forwarded to docker logs <container> (no prefix; the gateway's own output now lives in a per-profile s6-log file — see Where the logs go below — so the two streams don't clash).

Environment variable — Description — Default
HERMES_DASHBOARD — Set to 1 (or true / yes) to enable the supervised dashboard service — *(unset — service is registered but stays down)*
HERMES_DASHBOARD_HOST — Bind address for the dashboard HTTP server — 0.0.0.0
HERMES_DASHBOARD_PORT — Port for the dashboard HTTP server — 9119
HERMES_DASHBOARD_INSECURE — Deprecated / no-op. Formerly bypassed the auth gate; as of the June 2026 hardening it no longer disables authentication. A non-loopback bind always requires an auth provider — *(ignored — configure a provider instead)*

The dashboard inside the container defaults to binding 0.0.0.0 — without it, the published -p 9119:9119 port would not be reachable from the host. To restrict the bind to container loopback (for sidecar / reverse-proxy setups), set HERMES_DASHBOARD_HOST=127.0.0.1.

The dashboard's auth gate engages automatically when both of the following are true:

The bind host is non-loopback (e.g. the default 0.0.0.0 inside the container), and
A DashboardAuthProvider plugin is registered.

There are three bundled ways to satisfy the second condition:

Username/password — the simplest for a self-hosted / on-prem / homelab container on a trusted network or behind a VPN: set HERMES_DASHBOARD_BASIC_AUTH_USERNAME + HERMES_DASHBOARD_BASIC_AUTH_PASSWORD (and HERMES_DASHBOARD_BASIC_AUTH_SECRET for restart-stable sessions). Not suitable for direct public-internet exposure.
OAuth (Nous Portal) — for hosted/public deploys: the dashboard_auth/nous provider activates whenever HERMES_DASHBOARD_OAUTH_CLIENT_ID is set.
Self-hosted OIDC — to authenticate against your own identity provider via standard OpenID Connect: the dashboard_auth/self_hosted provider activates when HERMES_DASHBOARD_OIDC_ISSUER + HERMES_DASHBOARD_OIDC_CLIENT_ID are set.

Whichever you choose, the gate redirects callers to a login page before they can reach any protected route. See Web Dashboard → Authentication for all three providers.

If no provider is registered and the bind is non-loopback, the dashboard fails closed at startup with a specific error pointing at the missing env var. There is no longer an escape hatch that serves the dashboard unauthenticated on a public bind: HERMES_DASHBOARD_INSECURE=1 is now a deprecated no-op (it logs a warning and is ignored). Configure a provider, or bind HERMES_DASHBOARD_HOST=127.0.0.1 and reach the dashboard over an SSH tunnel / Tailscale instead.

An unauthenticated public dashboard was the entry point for the June 2026 MCP-config persistence campaign: internet scanners reached exposed dashboards (and OpenAI API servers) and drove the agent into planting an SSH-key backdoor. The auth gate is now mandatory on every non-loopback bind. For a trusted-LAN / homelab box, the bundled username/password provider (HERMES_DASHBOARD_BASIC_AUTH_USERNAME + _PASSWORD) is the zero-infra way to satisfy it.

Running the dashboard as a separate container **is

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

Lire la page courante pour comprendre hermes agent docker.
Ouvrir le hub parent du cluster guides.
Passer ensuite aux pages complémentaires proposées dans « À lire ensuite ».
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.

Utiliser Hermes Agent avec Docker