Tutorial 16: Implantação com Docker

Bem-vindos de volta, exploradores do Hermes! No tutorial anterior, aprendemos a executar o Hermes Agent diretamente em nossas máquinas. Hoje, vamos elevar o nível: vamos colocar o Hermes dentro de um contêiner Docker. Isso é um divisor de águas para manter seu ambiente limpo, portátil e fácil de atualizar.

Duas Formas de o Docker Encontrar o Hermes

Antes de mergulharmos, é importante entender que o Docker e o Hermes Agent podem trabalhar juntos de duas maneiras distintas:

Executando o Hermes no Docker – O próprio agente vive dentro de um contêiner. É nisso que vamos focar hoje.
Docker como backend de terminal – O Hermes roda no seu host, mas cada comando que ele executa acontece dentro de um sandbox Docker persistente. Isso é ótimo para segurança e isolamento, mas é um assunto para outro dia.

Hoje, vamos nos dedicar à opção 1. A beleza dessa abordagem é que todos os seus dados — configuração, chaves de API, sessões, habilidades e memórias — ficam em um único diretório no seu host, montado no contêiner em /opt/data. O contêiner em si não tem estado, então você pode baixar uma nova versão e atualizar sem perder nada.

Início Rápido: Seu Primeiro Contêiner

Se você é novo no Hermes, o caminho mais fácil é criar um diretório de dados e executar o assistente de configuração interativamente. Ele vai guiá-lo na inserção das suas chaves de API e salvá-las em ~/.hermes/.env.

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

Um aviso importante: evite consoles VPS baseados em navegador (como o da Hetzner Cloud) para esses comandos. Eles costumam distorcer caracteres especiais como :, @ e =, o que pode corromper silenciosamente seus argumentos do docker run. Sempre conecte via SSH (ssh root@<host>) para uma entrada segura de copiar e colar. Se precisar usar o console do navegador, digite os comandos manualmente e verifique cada caractere.

Depois de entrar no assistente, é altamente recomendável configurar um sistema de chat (Telegram, Discord etc.) para que seu gateway tenha um destino para enviar mensagens.

Executando no Modo Gateway

Após a configuração, você vai querer executar o Hermes como um gateway de fundo persistente. É assim que ele se conecta às suas plataformas de chat e permanece ativo 24/7.

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

A flag -p 8642:8642 expõe o servidor de API compatível com OpenAI do gateway e o endpoint de saúde. Ela é opcional se você usa apenas plataformas de chat, mas é necessária se quiser que o painel ou ferramentas externas acessem seu gateway.

Aqui está um recurso novo bem legal: dentro da imagem Docker oficial, o gateway run agora é automaticamente supervisionado pelo s6-overlay. Isso significa que, se o processo do gateway travar, ele é reiniciado em segundos sem perder o contêiner. Você verá um aviso nos docker logs confirmando a atualização. Se quiser o comportamento antigo (em que o contêiner sai quando o gateway sai), use --no-supervise ou defina HERMES_GATEWAY_NO_SUPERVISE=1. Para produção, o padrão supervisionado é estritamente melhor.

Expondo o Servidor de API

Por padrão, o servidor de API é controlado por API_SERVER_ENABLED=true. Para expô-lo além de 127.0.0.1 dentro do contêiner, você precisará definir algumas variáveis de ambiente:

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

A API_SERVER_KEY deve ter pelo menos 8 caracteres — gere uma com openssl rand -hex 32. Importante: abrir qualquer porta em uma máquina exposta à internet é um risco de segurança. Não faça isso a menos que entenda completamente as implicações.

Executando o Painel

Quer um painel web para monitorar seu gateway? Defina HERMES_DASHBOARD=1 e exponha a porta 9119:

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

O painel também é supervisionado pelo s6, então ele reinicia automaticamente se travar. A saída dele vai para docker logs <container>.

Uma Nota sobre Salvaguardas de Loop de Ferramentas

Para gateways não supervisionados, considere ativar paradas forçadas para as salvaguardas de loop de ferramentas. O padrão é false, o que é adequado para sessões interativas onde um humano pode ver os avisos. Mas em um gateway não supervisionado, um agente preso em um loop pode nunca parar. Adicione isto ao config.yaml do seu perfil:

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

Concluindo

Essa é a história da implantação com Docker! Agora você tem um contêiner sem estado e atualizável, com todos os seus dados montados com segurança no host. No próximo tutorial, vamos explorar o painel em mais detalhes. Até lá, boa containerização!