Docker + Hermes Agent: Duas Maneiras de Usar

Se você já se perguntou como o Docker se encaixa no cenário do Hermes Agent, está no lugar certo. Na verdade, existem duas maneiras distintas de essas duas ferramentas trabalharem juntas, e vale a pena entender a diferença antes de começar a digitar docker run.

Os Dois Modos do Docker

Executando o Hermes DENTRO do Docker — o próprio agente vive dentro de um contêiner. Este é o foco principal deste guia.
Docker como backend de terminal — o Hermes roda na sua máquina host, mas cada comando que ele executa acontece dentro de um único sandbox Docker persistente. Esse sandbox sobrevive a chamadas de ferramentas, /new e até mesmo subagentes enquanto o processo do Hermes estiver ativo.

Este artigo cobre a opção 1. O ponto-chave: todos os seus dados (configuração, chaves de API, sessões, habilidades, memórias) ficam em um único diretório no seu host, montado em /opt/data dentro do contêiner. A imagem em si não tem estado, então você pode baixar uma nova versão a qualquer momento sem perder sua configuração.

Início Rápido: Primeira Configuração

Se esta é a sua primeira vez, crie um diretório de dados e inicie o contêiner de forma interativa para executar o assistente de configuração:

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

Isso abre o assistente, que pede suas chaves de API e as grava em ~/.hermes/.env. Você só precisa fazer isso uma vez. Já que está nessa, é um ótimo momento para configurar um sistema de chat (Telegram, Discord etc.) para que seu gateway tenha onde conversar.

⚠️ Um aviso importante: Evite consoles VPS baseados em navegador para esses comandos de instalação. Alguns provedores (como Hetzner) corrompem caracteres especiais — : pode chegar como ;, @ é renderizado incorretamente, e chaves de API coladas podem ser corrompidas silenciosamente. Sempre conecte via SSH para entrada de comandos segura com copiar-e-colar. Se precisar usar o console do navegador, digite os comandos manualmente e verifique cada :, @, = e /.

Dica de profissional: Dentro do contêiner, execute hermes setup --portal uma vez — o token de atualização persiste no seu volume montado ~/.hermes.

Executando em Modo Gateway

Depois de configurado, execute o contêiner em segundo plano como um gateway persistente:

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

A porta 8642 expõe o servidor de API compatível com OpenAI do gateway e o endpoint de saúde. Ela é opcional se você usar apenas plataformas de chat, mas é necessária se quiser que o dashboard ou ferramentas externas alcancem o gateway.

O Que Há de Novo: Gateway Supervisionado

Aqui está uma grande mudança: dentro da imagem oficial do Docker, gateway run agora é automaticamente supervisionado pelo s6-overlay. Se o gateway travar, ele reinicia em segundos sem perder o contêiner. O dashboard (quando habilitado) é supervisionado junto.

Você verá uma linha de rastro em docker logs confirmando a atualização. Para optar por sair e obter o comportamento antigo (saída do contêiner = saída do gateway), passe --no-supervise ou defina HERMES_GATEWAY_NO_SUPERVISE=1. Isso é útil para testes de fumaça em CI; para produção, o padrão supervisionado é estritamente melhor.

Paradas Bruscas no Loop de Ferramentas

Uma configuração importante para gateways não supervisionados: tool_loop_guardrails.hard_stop_enabled tem como padrão false. Isso é aceitável para sessões interativas onde um humano pode ver os avisos. Mas em implantações não supervisionadas, apenas avisos podem não impedir um agente preso em um loop. Se você quiser o comportamento de disjuntor, habilite-o no config.yaml do seu perfil:

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

Expondo o Servidor de API

O servidor de API é controlado por API_SERVER_ENABLED=true. Para expô-lo além de 127.0.0.1 dentro do contêiner, defina também API_SERVER_HOST=0.0.0.0 e uma API_SERVER_KEY (mínimo de 8 caracteres — gere uma com openssl rand -hex 32):

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

Nota de segurança: Abrir qualquer porta em uma máquina exposta à internet é um risco. Não faça isso a menos que entenda completamente as consequências.

Executando o Dashboard

O dashboard web integrado roda como um serviço supervisionado pelo s6-rc junto com o gateway no mesmo contêiner. Basta definir HERMES_DASHBOARD=1:

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

Se o dashboard travar, o s6-supervise o reinicia automaticamente após um pequeno intervalo. A saída dele vai para docker logs <container>.

Para Onde Vão os Logs

Para o mapa completo de roteamento (gateways por perfil, dashboard, reconciliador de inicialização e docker logs do contêiner inteiro), consulte a seção dedicada na documentação. A versão resumida: tudo acaba chegando em docker logs, mas com prefixos claros para você saber o que é o quê.

Concluindo

O Docker oferece uma maneira limpa e atualizável de executar o Hermes Agent. O contêiner não tem estado, seus dados ficam seguros no host, e a nova supervisão do s6 significa que seu gateway permanece ativo mesmo se travar. Seja executando uma configuração simples ou uma combinação completa de dashboard + servidor de API, os comandos acima resolvem em minutos.