Hermes Agent · deploy

Instalação do Hermes Agent da Nous Research num VPS Ubuntu, em container Docker, com dashboard web via túnel SSH e bot do Telegram conectado.

Este repositório é a parte automatizável do processo: em vez de digitar ~30 comandos à mão, você roda dois scripts e responde a um wizard.

---

O que você vai ter no final

• Agente AI persistente rodando 24/7 em container isolado
• Memória que atravessa sessões e canais
• Dashboard web (Sessions, Analytics, Models, Config, Keys)
• Bot do Telegram para conversar pelo celular
• Persona customizada via SOUL.md
• Skills bundled — claude-code, notion, linear, github, google-workspace…
• CLI no terminal: chat, tui, status, doctor

---

Pré-requisitos

Item	Detalhe
VPS	Ubuntu 22.04 ou 24.04 LTS — Hetzner, DigitalOcean, Hostinger, LuraHosting
Specs mínimos	4 GB RAM · 2 vCPUs · 30 GB disco
Specs ideais	8 GB RAM · 4 vCPUs — se for rodar várias skills em paralelo
Sua máquina	Mac ou Linux com terminal. Windows serve via WSL2
API key	Anthropic (console.anthropic.com) ou OpenRouter (openrouter.ai)
Telegram	Instalado, para criar o bot via @BotFather

Tempo estimado: 20–30 min, a maior parte esperando o download da imagem.

---

Instalação automática (Hetzner e outros com cloud-init)

Se você ainda vai criar o servidor, este é o caminho mais curto: o cloud-init.yaml faz tudo sozinho no primeiro boot — Docker, usuário hermes, containers no ar, firewall configurado.

Na Hetzner Cloud Console:

1. Add Server → Ubuntu 24.04 → tipo com 4 GB RAM ou mais (ex.: CPX21)
2. Marque a sua SSH key (importante — ela é copiada para o usuário hermes)
3. Abra Cloud config e cole o conteúdo de cloud-init.yaml
4. Create & Buy now

Acompanhe (leva ~3-5 min):

ssh root@SEU_IP 'tail -f /var/log/hermes-install.log'

Terminou quando o log fechar com instalação concluída. As instruções dos próximos passos, já com o seu IP preenchido, ficam em:

ssh root@SEU_IP 'cat /root/HERMES-PRONTO.txt'

Depois disso pule direto para o passo 3 (túnel) e o passo 4 (wizard) da seção abaixo — os passos 1 e 2 o cloud-init já fez.

Provedores sem campo de cloud-init (ou servidor já existente): siga a instalação manual abaixo.

---

Instalação manual

1 · Preparar o servidor (como root, uma vez só)

Instala Docker, cria o usuário não-root hermes e as pastas do projeto.

ssh root@SEU_IP

apt-get update -qq && apt-get install -y -qq git
git clone https://github.com/triadeflow-ia/hermes.git /opt/hermes-deploy
bash /opt/hermes-deploy/scripts/bootstrap-server.sh

O script pede uma senha para o usuário hermes — anote, você vai usá-la no túnel SSH. Ao final ele imprime o UID/GID.

Troque também a senha do root (passwd) se ela veio por e-mail do provedor.

2 · Subir os containers (como o usuário hermes)

su - hermes
git clone https://github.com/triadeflow-ia/hermes.git ~/hermes
cd ~/hermes && bash scripts/install.sh

O script gera o .env com o UID/GID corretos, baixa a imagem (~1 GB), sobe os dois containers e valida que o dashboard responde.

Um HTTP 405 na validação é sucesso. O curl -I usa HEAD e o endpoint raiz só aceita GET — o navegador abre normalmente.

3 · Abrir o dashboard (na SUA máquina, outro terminal)

O dashboard escuta só em 127.0.0.1 do VPS — de propósito, nunca fica exposto na internet. O acesso vem por um túnel SSH:

bash scripts/tunnel.sh SEU_IP

Ou, sem clonar o repo localmente:

ssh -N -L 9119:127.0.0.1:9119 hermes@SEU_IP

Deixe essa janela aberta e parada e acesse http://localhost:9119.

GATEWAY STATUS: STOPPED neste momento é normal — o gateway sobe depois do wizard.

4 · Configurar o agente (de volta ao servidor)

cd ~/hermes && make setup

Tenha em mãos, antes de começar:

• API key — sk-ant-... (Anthropic) ou sk-or-... (OpenRouter)
• Bot token — Telegram → @BotFather → /newbot → nome + username terminado em bot
• Seu User ID — Telegram → @userinfobot → /start → número de 9–10 dígitos

Respostas recomendadas:

Pergunta	Escolha	Por quê
Inference Provider	OpenRouter	Testa vários modelos com uma chave só. Anthropic se for usar só Claude
Modelo padrão	Haiku para Telegram, Sonnet para uso geral	Opus é lento e caro
Text-to-Speech	Keep current	Só ative se for usar voz
Terminal Backend	Local	"Local" = local ao container, você já está isolado
Max iterations	60	Cobre 90% dos casos; sobe depois se precisar
Tool Progress	all	Mostra cada ferramenta em tempo real
Compression Threshold	0.5	Comprime o histórico a 50% do contexto
Session Reset	Inactivity + daily	Sessões frescas; a memória persistente continua
Allowed User IDs	seu ID numérico	Nunca deixe vazio — sem allowlist, qualquer um que achar o bot gasta sua API key
Tools Configuration	Done	Os defaults cobrem quase tudo

Aplique e confira:

make restart
docker compose logs --tail 50 hermes | grep -i telegram

Procure por Telegram gateway started ou similar. Então mande "Oi, quem é você?" para o seu bot — a resposta chega em 3–8 s, e o dashboard passa a mostrar GATEWAY STATUS: RUNNING.

5 · Definir a persona

make soul     # copia o template e abre no editor
make restart

O SOUL.md é o primeiro bloco do system prompt — antes de regras, ferramentas e memória. Ele só vale em sessão nova: no chat CLI mande /reset; no Telegram, aguarde o reset automático.

Overlays temporários, sem mexer no arquivo: /personality teacher, /personality concise, /personality technical, e /personality sozinho para voltar ao SOUL.md.

---

Operação diária

make help       lista todos os comandos
make ps         estado dos containers
make logs       log do gateway em tempo real
make restart    reinicia (use após mexer no config.yaml)
make status     gateway, modelos, canais e skills
make doctor     diagnóstico completo
make chat       chat no terminal — bom para testar o SOUL.md
make update     atualiza para a última imagem oficial
make backup     .tar.gz de ~/.hermes

Ajustes por linha de comando:

docker exec -it hermes uv run hermes config set model anthropic/claude-haiku-4.5
docker exec -it hermes uv run hermes config set agent.max_turns 90
docker exec -it hermes uv run hermes config set telegram.allowed_users "123456789,987654321"

Dentro do container, o binário não está no PATH global — sempre uv run hermes <comando>. Os alvos do make já cuidam disso.

---

Estrutura

docker-compose.yml          dois serviços: gateway + dashboard
.env.example                tag da imagem, UID/GID, portas, caminho dos dados
Makefile                    atalhos de operação (make help)
SOUL.md.example             template de persona
scripts/bootstrap-server.sh etapa 1 — Docker + usuário (root)
scripts/install.sh          etapa 2 — .env + pull + up + validação (hermes)
scripts/tunnel.sh           túnel SSH do dashboard (sua máquina)
docs/TROUBLESHOOTING.md     erros comuns e correções
cloud-init.yaml             instalação automática no primeiro boot do servidor

Dois diretórios no servidor, com papéis distintos:

• ~/hermes/ — este repositório: compose, scripts, .env
• ~/.hermes/ — dados do agente: memória, skills, SOUL.md, config.yaml, API keys. Sobrevive a docker compose down e a troca de imagem.

---

Segurança

O que já vem coberto:

• Dashboard publicado só em 127.0.0.1 do host — inacessível pela internet
• Gateway (8642) também restrito a 127.0.0.1 por padrão, via GATEWAY_BIND
• Agente roda como usuário não-root
• Nenhuma credencial neste repositório (.env e SOUL.md estão no .gitignore)
• Allowlist do Telegram obrigatória no wizard

Recomendado antes de considerar isso produção:

• Chave SSH e PasswordAuthentication no em /etc/ssh/sshd_config
• ufw liberando só a porta 22, e fail2ban contra força bruta

Cuidado com ufw + Docker. O Docker insere as próprias regras de iptables e passa por cima do ufw: uma porta publicada em 0.0.0.0 fica acessível pela internet mesmo com o firewall "fechado". Por isso este repositório publica tudo em 127.0.0.1. Se algum dia precisar abrir o gateway, use também a cloud firewall do provedor (na Hetzner, o Firewall do Cloud Console), que age antes do host.

• Backup automático de ~/.hermes para outro lugar (S3, segundo VPS)
• Travar HERMES_TAG numa versão testada em vez de latest

---

Problemas?

Veja docs/TROUBLESHOOTING.md — cobre 405, connection reset, address already in use, permission denied no config.yaml, command not found, wizard travado e bot mudo.

---

Créditos

Hermes Agent é da Nous Research (imagem nousresearch/hermes-agent). Este repositório contém apenas a automação do deploy.

O passo a passo segue o guia Hermes — Instalação passo a passo, de Eduardo Cavalcanti (Bisnis Hub / Comunidade Claw Brasil).