Guías

Cómo instalar Hermes Agent en Mac con Docker

18 de mayo de 2026

Esta guía explica cómo ejecutar Hermes Agent en un Mac usando Docker Desktop. Docker aporta el entorno de ejecución y el Mac conserva los datos persistentes en una carpeta local.

Hermes Agent también puede usar claves API, pero aquí nos centramos en OpenAI Codex con ChatGPT OAuth. El orden recomendado es instalar Docker Desktop, ejecutar setup, configurar el provider, iniciar Hermes Agent y comprobar el dashboard en localhost:9119.

Resumen rápido

Instala y abre Docker Desktop para Mac.
Usa la imagen oficial nousresearch/hermes-agent.
Monta ~/.hermes en /opt/data para conservar configuración, OAuth, sesiones, skills y logs.
Ejecuta primero setup y luego elige OpenAI Codex con hermes model.
Con el dashboard activo, http://localhost:9119 debe abrirse en el navegador.

Requisitos

Requisito	Uso
Mac	Funciona con Apple Silicon o Intel, pero el instalador de Docker debe coincidir.
Docker Desktop	Necesario para ejecutar el contenedor de Hermes Agent.
Terminal	Para comandos Docker, setup, OAuth y logs.
Cuenta de ChatGPT	Necesaria para conectar OpenAI Codex con ChatGPT OAuth.
Internet	Necesario para descargar la imagen y completar el login OAuth.

Diagrama de un Mac con Docker Desktop, un contenedor de Hermes Agent y un volumen persistente — Docker ejecuta Hermes Agent y `~/.hermes` conserva los datos en el Mac.

Qué aporta Docker

Hermes Agent es un runtime de AI agent de NousResearch. La documentación oficial describe varias formas de usarlo, como local installation, Docker execution y Docker terminal backend. Esta guía se centra en ejecutar Hermes Agent dentro de un contenedor Docker.

La ventaja es mantener el runtime más aislado. No necesitas instalar Python, Node.js, browser automation dependencies ni herramientas relacionadas directamente en macOS. A cambio, Docker Desktop debe estar iniciado y el acceso a archivos debe hacerse mediante carpetas montadas explícitamente.

Hermes Agent usa /opt/data como ubicación de datos dentro del contenedor. Por eso esta guía conecta ~/.hermes del Mac con /opt/data.

Instalar Docker Desktop

Descarga Docker Desktop desde la documentación oficial para Mac. Elige Apple Silicon para Macs con chip M y la versión Intel para modelos antiguos.

El flujo básico es:

Descargar Docker Desktop desde la página oficial para Mac.
Abrir Docker.dmg y mover Docker a la carpeta Aplicaciones.
Iniciar Docker Desktop desde Aplicaciones.
Revisar los permisos iniciales y la pantalla de términos.
Esperar a que el icono de Docker quede estable en la barra de menú.

Después comprueba:

docker --version

Si no funciona, Docker Desktop puede no estar iniciado o la integración CLI aún no está lista.

Flujo de instalación de Docker Desktop y comprobación con docker version — Comprueba Docker Desktop antes de iniciar la imagen de Hermes Agent.

Por qué montar `~/.hermes`

El volumen evita perder configuración y autenticación cuando se elimina el contenedor. Usa siempre:

-v ~/.hermes:/opt/data

Diagrama que conecta la carpeta ~/.hermes del Mac con /opt/data en el contenedor Docker — El mount `~/.hermes:/opt/data` conserva ajustes, sesiones, OAuth, skills y logs.

Primer inicio: ejecutar setup

Crea la carpeta de datos y ejecuta el setup oficial:

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

--rm elimina el contenedor temporal al terminar, pero los archivos de /opt/data quedan en ~/.hermes.

El setup wizard puede crear o actualizar:

Ruta	Función
`~/.hermes/.env`	Secrets para providers con API key.
`~/.hermes/config.yaml`	Configuración de modelo, backend, gateway y herramientas.
`~/.hermes/SOUL.md`	Comportamiento base del agent.
`~/.hermes/sessions/`	Historial de sesiones.
`~/.hermes/memories/`	Memoria a largo plazo, si está activa.
`~/.hermes/skills/`	Skills instaladas.
`~/.hermes/logs/`	Logs de ejecución.

Los prompts exactos pueden cambiar según la versión de Hermes Agent, pero esta guía práctica ayuda:

Prompt de setup	Elección práctica
Model provider	Elige `OpenAI Codex` o una opción `Codex`. Si no aparece, termina setup y ejecuta luego `hermes model`.
Authentication method	Los providers con API key guardan valores en `.env`. ChatGPT OAuth guarda tokens en un auth store como `auth.json`.
Chat system o gateway integration	Telegram, Discord o Slack pueden configurarse después si no los usarás de inmediato. Si usarás gateway de forma permanente, puede ser cómodo configurarlo aquí.
Defaults poco claros	Mantén los defaults primero y ajusta `config.yaml` cuando la instalación ya funcione.

En resumen, deja que setup cree los archivos base y, si la selección de provider no está clara, vuelve a abrirla con hermes model.

Comprueba:

ls -la ~/.hermes

Comprueba también que exista config.yaml. No publiques el archivo completo; basta con ver localmente el inicio.

sed -n '1,80p' ~/.hermes/config.yaml

No muestres ni compartas .env, porque puede contener secrets. Para revisar solo si existe:

ls -la ~/.hermes/.env

Si setup termina pero falta ~/.hermes/config.yaml o la carpeta está vacía, revisa primero el volume mount. El comando debe incluir -v ~/.hermes:/opt/data.

Configurar ChatGPT OAuth

Si el provider no quedó configurado, abre el selector:

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

Elige OpenAI Codex o la entrada Codex más cercana. Si aparece una URL o device code, ábrelo en el navegador del Mac y accede con ChatGPT.

Algunas versiones también admiten:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

El token OAuth no debe vivir solo dentro de un contenedor descartable. Se guarda bajo la carpeta montada ~/.hermes, por ejemplo en un auth store como auth.json. Así puedes recrear el contenedor sin perder la configuración del provider.

Diagrama de login ChatGPT OAuth conectado a un contenedor Docker de Hermes Agent — ChatGPT OAuth conecta OpenAI Codex sin pegar una OpenAI API key en el comando.

Ejecutar Hermes Agent

Inicia Hermes Agent de forma interactiva:

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

Si se abre la sesión interactiva, la instalación básica funciona. Usa el mismo volume mount en todos los comandos.

Las opciones principales significan:

Option	Significado
`docker run`	Inicia un contenedor nuevo.
`-it`	Abre una sesión interactiva de terminal.
`--rm`	Elimina el contenedor temporal al salir.
`-v ~/.hermes:/opt/data`	Conecta la carpeta `~/.hermes` del Mac con `/opt/data` en el contenedor.
`nousresearch/hermes-agent`	Usa la imagen Docker oficial de Hermes Agent.

Comprobar el dashboard en `localhost:9119`

Después de setup, configuración del provider e inicio interactivo, comprueba la imagen y la versión:

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

Para revisar el estado OAuth, usa la misma carpeta de datos:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth list

Para gateway y dashboard en segundo plano:

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

Abre http://localhost:9119 o http://127.0.0.1:9119. El dashboard es una interfaz local para configuración, sesiones, logs y skills.

Si no carga:

curl -I http://127.0.0.1:9119

Los logs muestran detalles de ejecución:

docker logs --tail 50 hermes

Las líneas del dashboard pueden aparecer con [dashboard].

Detén y elimina el contenedor en segundo plano así:

docker stop hermes
docker rm hermes

Problemas comunes

Síntoma	Qué revisar
`Cannot connect to the Docker daemon`	Docker Desktop no está iniciado.
`docker: command not found`	La CLI de Docker no está disponible en Terminal.
No se abre la URL OAuth	Copia la URL o el device code al navegador del Mac.
No aparece OpenAI Codex provider	Descarga la imagen más reciente de Hermes Agent y revisa de nuevo el menú `hermes model`.
Se pierde la configuración	Falta o cambia el mount `-v ~/.hermes:/opt/data`.
Permission error	Verifica que el usuario actual de macOS pueda escribir en `~/.hermes`.
No abre el dashboard	Revisa `-p 9119:9119`, `-e HERMES_DASHBOARD=1` y logs `[dashboard]`.
Conflicto de puertos	Otro proceso usa `8642` o `9119`.

En Macs Apple Silicon, Docker Desktop suele manejar las diferencias de arquitectura mientras no fuerces una imagen Intel-only. Empieza con la imagen oficial latest y una instalación actualizada de Docker Desktop.

Flujo para revisar Docker, OAuth, volume mount, logs y dashboard — Revisa Docker, OAuth, el volume mount, los logs y el puerto del dashboard.

Actualizar o eliminar

Para actualizar:

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
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

Para eliminar:

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

Elimina ~/.hermes solo si también quieres borrar ajustes, tokens OAuth, sesiones, skills y logs.

rm -rf ~/.hermes

Resumen final

El flujo fiable es Docker Desktop, setup, OpenAI Codex con ChatGPT OAuth, mount ~/.hermes:/opt/data y comprobación de http://localhost:9119 en modo gateway.