Hermes Agent Docker: guia completo de implantação para 2026

Two Docker Modes Explained – Escolha antes de começar

A maioria dos guias ignora totalmente esta decisão e vai para docker run. Não. Os dois modos têm perfis operacionais e de segurança significativamente diferentes.

Mode 1 — Hermes correndo dentro de um contêiner

Hermes e todas as suas dependências vivem dentro da imagem. Você gerencia o estado por meio de volumes nomeados. A política de reinicialização do contêiner o mantém ativo durante as reinicializações. Este é o padrão de produção mais comum.

• Separação limpa do host – sem gravações acidentais em sua máquina
• Portabilidade total; reimplantar em qualquer lugar com o mesmo arquivo de composição
• Sobrecarga um pouco maior do que a execução nativa

Mode 2 — Docker como sandbox de back-end de terminal

Aqui, o Hermes é executado diretamente no host (ou em um contêiner) e chama o daemon do Docker para ativar contêineres efêmeros para execução do shell. Você configura DOCKER_HOST para que Hermes possa acessar o daemon:

export DOCKER_HOST=unix:///var/run/docker.sock   # Linux
export DOCKER_HOST=tcp://host.docker.internal:2375  # Windows/Mac (Docker Desktop)

Prerequisites and Environment Setup

Antes de extrair qualquer imagem, confirme:

• Docker Engine 24+ ou Docker Desktop 4.26+
• Uma chave de API LLM pronta: OpenAI (OPENAI_API_KEY), Anthropic (ANTHROPIC_API_KEY) ou um endpoint local Ollama
• Acesso de saída à Internet na porta 443 (para chamadas de API LLM)
• Pelo menos 2 GB RAM alocado para o contêiner (4 GB recomendados para configurações apoiadas por Ollama)

Windows-Specific Setup (Docker Desktop + WSL2)

O Windows é onde a maioria das implantações do Docker são interrompidas silenciosamente. Fique atento a estes:

# Correct — Docker Desktop translates this automatically
volumes:
  - hermes_data:/root/.hermes

DOCKER_HOST=npipe:////./pipe/docker_engine

[wsl2]
memory=4GB
processors=2

Início rápido – execute Hermes Agent com Docker em 5 minutos

Extraia a imagem oficial e execute o assistente de configuração:

# Pull the latest image
docker pull nousresearch/hermes-agent:latest

# Run with a persistent volume for state
docker run -it \
  -v hermes_home:/root/.hermes \
  -e OPENAI_API_KEY=your_key_here \
  nousresearch/hermes-agent:latest

O assistente de configuração é lançado na primeira execução. Ele solicitará que você:

1. Selecione seu provedor LLM (OpenAI, Anthropic, Ollama ou endpoint personalizado)
2. Insira sua chave de API ou URL de endpoint
3. Configure o back-end do terminal (nativo ou sandbox do Docker)

Depois de concluído, verifique se a sessão está funcionando:

> hello

Production Deployment with Docker Compose

O comando docker run simples funciona para teste. Para qualquer coisa persistente, use Compose.

version: "3.9"

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    restart: unless-stopped
    stdin_open: true
    tty: true

    environment:
      # Use environment secrets — never hardcode keys in compose files
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      HERMES_LOG_LEVEL: info

    volumes:
      - hermes_home:/root/.hermes         # Config + conversation history
      - hermes_skills:/root/.hermes/skills # Skill store — see next section

    deploy:
      resources:
        limits:
          memory: 2G
          cpus: "1.5"

    healthcheck:
      test: ["CMD", "hermes", "--health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  hermes_home:
  hermes_skills:

Armazene suas chaves de API em um arquivo .env (nunca confirmado para controle de versão):

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Preservando as habilidades da Hermes em reconstruções de contêineres

Esta é a preocupação de produção mais negligenciada. Hermes armazena as habilidades aprendidas separadamente da configuração geral. Monte esses caminhos explicitamente:

Ao atualizar a imagem:

docker compose pull
docker compose up -d   # Named volumes persist automatically

Advanced Topology — Configuração do Host-Docker (contêiner irmão)

Essa arquitetura é usada quando você deseja que o Hermes orquestre contêineres irmãos para execução isolada de código — por exemplo, executando código enviado pelo usuário com segurança.

┌─────────────────────────────────┐
│         Docker Host             │
│                                 │
│  ┌──────────────┐               │
│  │ hermes-agent │◄──socket──────┤── /var/run/docker.sock
│  │  container   │               │
│  └──────┬───────┘               │
│         │ docker run (sibling)  │
│  ┌──────▼───────┐               │
│  │  sandbox-1   │  (ephemeral)  │
│  └──────────────┘               │
└─────────────────────────────────┘

Componha a configuração para esta topologia:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    restart: unless-stopped
    environment:
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      DOCKER_HOST: unix:///var/run/docker.sock
      HERMES_TERMINAL_BACKEND: docker
    volumes:
      - hermes_home:/root/.hermes
      - /var/run/docker.sock:/var/run/docker.sock  # Socket mount
    group_add:
      - "999"   # docker group GID — adjust to match your host

Connecting Hermes to Claude via Telegram Bot

O guia escrito No atualmente cobre isso - é mostrado apenas em formato de vídeo. Aqui está a configuração completa.

/newbot
→ Name: Hermes Agent
→ Username: your_hermes_bot
→ Save the token: 123456:ABC-DEF...

environment:
  ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
  HERMES_LLM_PROVIDER: anthropic
  HERMES_TELEGRAM_TOKEN: ${TELEGRAM_BOT_TOKEN}
  HERMES_TELEGRAM_ALLOWED_USERS: "your_telegram_user_id"

docker compose up -d

Implantação de múltiplas arquiteturas (Nível gratuito ARM64/Oracle/Raspberry Pi)

A imagem nousresearch/hermes-agent é enviada como um manifesto multi-arch. ARM64 é suportado — extraia-o explicitamente em hosts ARM:

# Oracle Free Tier (Ampere A1) or Raspberry Pi 4/5
docker pull --platform linux/arm64 nousresearch/hermes-agent:latest

# Verify the architecture
docker inspect nousresearch/hermes-agent:latest | grep Architecture

Problemas conhecidos específicos do ARM:

• Algumas quantizações do modelo Ollama (Q8) são executadas mais lentamente no ARM; prefira Q4_K_M para inferência local
• Se você clicar em exec format error, confirme que está usando a sinalização --platform linux/arm64
• Docker Desktop no Apple Silicon lida com ARM nativamente – nenhum sinalizador de plataforma é necessário

Solução de problemas comuns de falhas do Docker Hermes Agent

Uma tabela de referência para as falhas que você provavelmente encontrará:

Perguntas frequentes

Considerações finais: lista de verificação e próximas etapas

O ciclo de aprendizagem é o que separa o Hermes de todos os outros agentes que você executou no Docker. A configuração acima garante que o loop realmente acumula – não redefinições – sempre que você envia uma atualização.

Antes de chamar uma implantação pronta para produção, confirme:

• ☐ Volumes nomeados criados para hermes_home e hermes_skills
• ☐ Chaves de API armazenadas em .env, não codificadas no compose
• ☐ Política restart: unless-stopped ativa
• ☐ Aprovação no exame de saúde: docker inspect hermes-agent --format='{{.State.Health.Status}}'
• ☐ Rotação de log configurada (max-size, max-file)
• ☐ Limites de recursos definidos para evitar o esgotamento da memória
• ☐ Assistente de configuração concluído e primeira sessão de chat verificada
• ☐ (Se Mode 2) Montagem de soquete Docker confirmada e proxy de soquete considerado

Próximas etapas para obter valor imediatamente:

1. Execute algumas tarefas reais – resumo de arquivos, revisão de código, pesquisa na web – para semear a biblioteca de habilidades
2. Após 10 a 15 tarefas, execute hermes skills list para ver o que foi aprendido
3. Revise o Nous Research GitHub para obter documentos de configuração de agente que abrangem modelos de habilidades personalizados e ajuste de memória
4. Se você estiver no nível gratuito Oracle, configure um docker compose pull && docker compose up -d baseado em cron para atualizações de imagem com tempo de inatividade zero, preservando o estado aprendido