Como rodar o Hermes Agent no Docker (Self-Hosted)

Por que o Docker é a forma padrão de rodar o Hermes Agent

O Hermes Agent é distribuído como contêiner Docker como destino de implantação principal. A imagem inclui o gateway, o dashboard, as dependências de runtime e uma configuração padrão sensata, então você não precisa brigar com versões do Python, bibliotecas do sistema ou problemas de PATH no host. Você fornece um host com Docker instalado, um pequeno volume persistente para o estado e a sua API key do provedor. O contêiner faz o resto.

Um setup self-hosted típico se parece com isto:

Um contêiner gateway expondo a porta 8642 para a API compatível com OpenAI e o endpoint de health.
Um volume nomeado persistente para sessões, memória, skills aprendidas e configuração.
Um arquivo .env com as chaves do provedor e as credenciais do Telegram.
Opcionalmente, um contêiner sidecar do dashboard lendo o mesmo diretório de dados em modo somente leitura.

Todo o resto - atualizações, restarts, rotação de logs - é tratado pelo próprio Docker. Este post percorre essa configuração de ponta a ponta, depois mostra o layout docker-compose pronto para produção e os detalhes que vale a pena conhecer antes de colocar o agente em um host público.

Se você ainda não escolheu entre hospedar você mesmo e usar uma versão gerenciada, leia primeiro self-hosted vs gerenciado do Hermes Agent. O resto deste guia assume que você decidiu rodar o contêiner por conta própria.

Pré-requisitos

Você precisa de:

Um host com Docker 24+ instalado (VPS Linux, macOS via Docker Desktop ou Windows via WSL2).
Pelo menos 1 vCPU e 2 GB de RAM. A recomendação oficial é 2 vCPU e 8 GB para uso concorrente confortável.
Uma API key de provedor (OpenAI, Anthropic, OpenRouter ou qualquer endpoint compatível com OpenAI).
Cerca de 2 GB de espaço livre em disco para a imagem, mais margem para o crescimento do volume de dados.

Um VPS de 5 dólares de qualquer provedor decente atende ao mínimo. O agente consome pouca CPU e pouca E/S quando não está raciocinando ativamente - a maior parte do dia ele fica ocioso esperando mensagens do Telegram ou tarefas agendadas.

Passo 1 - Crie o diretório de dados

O contêiner persiste tudo em /data dentro da imagem. No host, decida onde esse diretório vai morar. A convenção é ~/.hermes/data:

mkdir -p ~/.hermes/data

Esse único diretório guarda histórico de sessões, memória vetorial, skills aprendidas, segredos criptografados e a configuração do usuário. Faça backup dele e você fez backup do agente inteiro. Perca-o e começa do zero - o contêiner em si é efêmero.

Passo 2 - Assistente de configuração inicial

Rode o contêiner em modo interativo na primeira vez para que ele possa pedir as chaves e gravá-las em ~/.hermes/.env:

docker run -it --rm \
  -v ~/.hermes:/root/.hermes \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest setup

O assistente pergunta sobre:

O provedor LLM padrão (OpenAI, Anthropic, OpenRouter, custom).
A API key do provedor.
Token opcional do bot do Telegram e lista de usuários permitidos.
Chaves opcionais do provedor de voz (apenas se você for habilitar o modo voz).

Os valores são gravados em ~/.hermes/.env no host. Trate esse arquivo como segredo - chmod 600 ~/.hermes/.env e nunca commite no git.

Um terminal mostrando o assistente de configuração Docker do Hermes Agent pedindo uma API key da OpenAI, com o caminho do novo arquivo .env visível no topo

Passo 3 - Rode o gateway persistente

Depois que o assistente terminar, a forma de longa duração do mesmo contêiner inicia o gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -p 8642:8642 \
  --env-file ~/.hermes/.env \
  -v ~/.hermes/data:/data \
  ghcr.io/nousresearch/hermes-agent:latest gateway

Detalhamento de cada flag:

-d roda o contêiner em segundo plano, em modo detached.
--restart unless-stopped traz ele de volta automaticamente após reinícios e quedas do host.
-p 8642:8642 expõe a API compatível com OpenAI e o endpoint /health.
--env-file ~/.hermes/.env injeta as chaves do provedor sem embuti-las na imagem.
-v ~/.hermes/data:/data é a linha da persistência - apague essa linha e o agente esquece tudo a cada restart.

Verifique se está saudável:

curl http://localhost:8642/health
# {"status":"ok","gateway":"running"}

Se você está rodando em um VPS que quer acessar do seu notebook, não exponha a porta direto em 0.0.0.0. Coloque um proxy reverso (Caddy, Nginx, Traefik) na frente com HTTPS, ou exponha a porta apenas via Tailscale ou WireGuard. A API compatível com OpenAI não tem autenticação por padrão - ela confia na rede em que está.

Passo 4 - Use docker-compose em produção

Para qualquer coisa além de um teste rápido, mude para docker-compose.yaml. Ele torna a configuração revisável, reiniciável como uma unidade e fácil de estender com o sidecar opcional do dashboard:

services:
  gateway:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    command: gateway
    ports:
      - "127.0.0.1:8642:8642"
    env_file:
      - ./.env
    volumes:
      - hermes_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8642/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 1G

  dashboard:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    command: dashboard
    ports:
      - "127.0.0.1:8643:8643"
    volumes:
      - hermes_data:/data:ro
    depends_on:
      gateway:
        condition: service_healthy

volumes:
  hermes_data:

Alguns detalhes que vale notar:

O contêiner do dashboard monta o volume de dados em somente leitura (:ro). Ele só lê sessões e memória para renderizar a UI, nunca escreve. É isso que permite rodar os dois com segurança.
A porta do gateway está amarrada em 127.0.0.1 no host. Exposição pública é trabalho do proxy reverso, não do Docker.
healthcheck permite que depends_on espere o gateway antes de iniciar o dashboard.
Um limite de memória de 1 GB é confortável para cargas em escala pessoal. Aumente se tiver tráfego alto.

Suba o stack com docker compose up -d e siga os logs com docker compose logs -f.

Um diagrama de arquitetura simplificado mostrando o host Docker com dois contêineres, gateway e dashboard, compartilhando um único volume nomeado montado somente leitura no lado do dashboard

Passo 5 - Atualizações

O contêiner é a unidade de atualização. Para passar para uma nova release:

docker compose pull
docker compose up -d

O Compose recria o gateway com a nova imagem mantendo o volume nomeado intacto. Memória, skills e conexões do Telegram voltam exatamente como estavam. Fixe uma tag específica em vez de latest para produção - ghcr.io/nousresearch/hermes-agent:0.42 em vez de :latest - para que as atualizações sejam explícitas.

Antes de qualquer atualização, faça um snapshot do volume:

docker run --rm \
  -v hermes_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/hermes-$(date +%F).tar.gz -C /data .

Restaurar é o mesmo comando ao contrário. É mais rápido e mais seguro do que fazer rollback só da imagem.

Erros comuns

Dois contêineres gateway no mesmo volume. Os armazenamentos de sessão e memória do Hermes assumem um único writer. Rodar dois contêineres gateway contra o mesmo /data corrompe os arquivos em minutos. O sidecar do dashboard está OK porque é somente leitura.

Faltou o --env-file. Sem ele, o contêiner sobe mas a primeira chamada ao LLM falha com 401. Cheque docker logs hermes se as respostas nunca chegarem.

Bindar em 0.0.0.0:8642 num VPS público. A API não tem autenticação embutida. Sempre coloque um proxy reverso na frente exigindo HTTPS mais autenticação básica ou uma restrição de rede (Tailscale, regras de firewall).

Volumes anônimos. Se você esquecer a linha -v ~/.hermes/data:/data, o Docker cria um volume anônimo. Ele sobrevive a restarts mas é difícil de achar e fácil de podar por engano. Use sempre um volume nomeado ou um bind ao host.

Reconexão do bot do Telegram. Quando você atualiza, o bot se reconecta sozinho. Se não reconectar, cheque se TELEGRAM_BOT_TOKEN ainda está no .env e se o contêiner tem saída para internet.

Para problemas específicos do Telegram, Solução de problemas do Hermes Agent no Telegram cobre a parte de mensageria em mais detalhes.

Pule toda a parte de contêineres

Rodar o Hermes em Docker é direto, mas o host continua sendo sua responsabilidade: backups, certificados TLS, rotação de logs, patches do SO e cadência de atualizações. Para um agente pessoal isso está OK - uma tarde de domingo de setup e talvez dez minutos por mês depois.

Se você prefere pular tudo isso, o Hermify roda o seu agente Hermes em um contêiner gerenciado e isolado, com segredos criptografados em repouso, atualizações automáticas, snapshots diários do volume e Telegram conectado pelo dashboard em dois toques. Você fornece a chave do provedor; a plataforma cuida de todo o resto.