O mapa antes da estrada
Você não está instalando um aplicativo de chat. Está colocando um agente com terminal numa máquina que nunca desliga, e abrindo um canal privado até ele.
Nenhuma porta precisa ser aberta. O Telegram funciona por long polling: é o Hermes que abre conexões de saída e pergunta se há mensagem nova. Firewall fechado e bot funcionando não são contraditórios; são o desenho certo.
Duas trilhas, um destino
| Critério | Trilha Rápida | Trilha Blindada |
|---|---|---|
| Como instala | Template one-click da Hostinger | Ubuntu 24.04 do zero + Docker Compose |
| Tempo | ~40 minutos | ~90 minutos |
| Versão do Hermes | A que o template entregar | Tag fixa e imutável, escolhida por você |
| Firewall e Fail2Ban | Padrão do provedor | Configurados à mão, negando entrada |
| Onde ficam os segredos | ~/.hermes/.env dentro do contêiner | /opt/hermes/data/.env no host |
| Para quem | Primeira VPS da vida; quer o agente no ar hoje | Vai deixar rodando meses; quer rollback previsível |
A diferença mais traiçoeira é o caminho do arquivo de segredos. Metade dos erros de “o bot não responde” nasce de editar o .env de uma trilha enquanto o agente lê o da outra.

Rápida não é pior. Blindada não é exagero.
A Rápida entrega valor no mesmo dia e é reversível: um snapshot desfaz tudo. A Blindada custa uma tarde e devolve controle de versão, firewall auditável e rollback ensaiado. Se esta é sua primeira VPS, comece pela Rápida e migre depois — o conteúdo dos capítulos 05 em diante vale igual nas duas.
Sua folha de instalação
Quatro valores atravessam o guia inteiro. Anote fora deste arquivo, num gerenciador de senhas — nunca em bloco de notas, print ou conversa.
O que você precisa ter
Conta Hostinger com VPS, conta no Telegram no celular, credencial de um provedor de IA e um gerenciador de senhas aberto.
O que você vai anotar
VPS_IP, TELEGRAM_BOT_TOKEN, TELEGRAM_USER_ID (numérico, não o @username) e o provedor escolhido.
A Oracle dá 2 OCPUs ARM, 12 GB de RAM e 200 GB de disco sem prazo de validade, e o Hermes roda em ARM sem alteração. O cadastro é mais rígido e a rede tem duas camadas de firewall em vez de uma — o apêndice cobre as duas. Ler o apêndice: VPS grátis na Oracle.
| Recurso | Mínimo | Confortável |
|---|---|---|
| CPU | 1 vCPU | 2 vCPU |
| RAM | 2 GB sem automação de navegador | 4 GB — 8 GB se for usar browser pesado |
| Disco | 20 GB | 40 GB ou mais |
| Sistema | Ubuntu 24.04 LTS x86_64 | |
Antes de instalar qualquer coisa, abra VPS → Snapshots & Backups no hPanel e crie um snapshot chamado antes-hermes. Se algo der errado em qualquer etapa, você restaura e recomeça limpo — em vez de fazer arqueologia num servidor meio configurado.
Consoles web às vezes alteram caracteres especiais em tokens e caminhos. No Windows, PowerShell ou Windows Terminal. Se a VPS já roda outra coisa — site, n8n, banco — não reinstale o sistema por cima: contrate uma VPS separada.
Trilha Rápida: o template one-click
A Hostinger publica um template oficial do Hermes Agent. Ele entrega a VPS já com Docker e o contêiner montados — zero instalação manual.
Se a VPS ainda vai ser contratada
Escolha o plano na aplicação Hermes Agent do catálogo da Hostinger.
A instalação do template é automática. Aguarde o provisionamento terminar.
O hPanel pede as credenciais do terminal web e do Docker Manager. Guarde no gerenciador de senhas.
Em VPS → Docker Manager, o projeto do Hermes deve aparecer rodando.
Se você já tem VPS na Hostinger
hPanel → VPS → Configurações → SO e Painel → Sistema Operacional → Mudar SO → aba Aplicações → Hermes Agent.
Sites, bancos e automações que estiverem nessa máquina desaparecem. Faça backup antes ou contrate uma VPS separada para o Hermes.
Entrar no contêiner
docker ps
docker exec -it NOME_DO_CONTAINER bashDentro do contêiner, rode hermes --help. Se listar os comandos, você está no lugar certo. Se der command not found, você está fora do contêiner — repita o docker exec.
Nesta trilha, tudo que os próximos capítulos mandarem rodar acontece dentro do contêiner, e o arquivo de segredos é ~/.hermes/.env. Pule agora para o capítulo 05.
Trilha Blindada: você escolhe cada peça
Ubuntu limpo, firewall que nega entrada por padrão, Fail2Ban ligado e um Compose com tag imutável. Atualização vira decisão deliberada, não efeito colateral.
4.1 Sistema e proteção básica
apt update
apt full-upgrade -y
apt install -y ca-certificates curl gnupg ufw fail2ban unattended-upgrades
timedatectl set-timezone America/Sao_Paulo
reboot4.2 Firewall: abrir somente o SSH
ufw default deny incoming
ufw default allow outgoing
ufw allow OpenSSH
ufw enable
ufw status verbosePorta 22 permitida, política de entrada negada. Não crie regra para 8642 nem 9119 — o Telegram não precisa de nenhuma das duas.
4.3 Fail2Ban
systemctl enable --now fail2ban
fail2ban-client status sshdSe sshd não aparecer entre as jails, crie /etc/fail2ban/jail.d/sshd.local com enabled = true, backend = systemd, maxretry = 5, findtime = 10m e bantime = 1h, e reinicie o serviço.
4.4 Docker pelo repositório oficial
O pacote docker-ce não existe nos repositórios do Ubuntu — o docker.io que vem de fábrica é outra coisa, mantida por terceiros e sempre atrasada. Por isso o repositório oficial da Docker precisa entrar antes do apt install, com a chave que o autentica.
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
apt-cache policy docker-ce # deve mostrar um "Candidate:" com versão<<EOF por <<'EOF'Os dois $(...) do bloco precisam ser resolvidos na hora — eles preenchem o nome da sua versão do Ubuntu e a arquitetura da máquina. Com o delimitador entre aspas, o shell grava o texto literal e o apt update falha com repositório inválido.
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run --rm hello-world
sudo docker compose version4.5 A estrutura persistente
sudo install -d -m 700 /opt/hermes/data
cd /opt/hermes
sudo nano compose.yamlservices:
hermes:
image: nousresearch/hermes-agent:v2026.7.30
container_name: hermes-agent
restart: unless-stopped
command: gateway run
environment:
TZ: America/Sao_Paulo
volumes:
- /opt/hermes/data:/opt/data
cpus: 2.0
mem_limit: 4g
stop_grace_period: 60s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"Não há ports:, não há privileged: true e não há montagem de /var/run/docker.sock. A tag é explícita: nunca use latest, senão um pull de rotina troca a sua versão sem aviso.
4.6 Baixar, validar e configurar
sudo docker compose config
sudo docker compose pull
sudo docker compose run --rm hermes --version
sudo docker compose run --rm hermes setupNo assistente, habilite só o necessário para a primeira fase: arquivos, terminal, memória, skills, busca web, cron e Telegram. Deixe para depois navegador pesado, WhatsApp, e-mail, MCPs e subagentes.
Em 10/08/2026, a release mais recente era a v0.20.0 / v2026.8.3, com um relato aberto de crescimento de memória capaz de derrubar o gateway. Não é uma condenação da versão nova: é escolha conservadora para uma máquina que precisa ficar de pé sozinha. Confira as notas de release antes de mudar a tag.
O cérebro: escolher e testar o modelo
O Hermes é agnóstico de modelo. O que muda entre as rotas é quem cobra, quem autentica e quanto controle financeiro você tem.
| Rota | Quando escolher | O que observar |
|---|---|---|
| OpenRouter | Quer teto de gasto explícito, muitos modelos e troca a quente. | Exige chave e crédito. Defina limite por chave — é seu seguro contra fatura surpresa. |
| OpenAI Codex | Já tem assinatura e quer começar sem gerenciar chave. | Login por código de dispositivo. Sujeito aos limites do plano. |
| Nous Portal | Quer o caminho mais integrado ao Hermes, com busca, imagem e voz juntos. | O login é OAuth, mas os créditos de uso exigem assinatura paga. |
A rota padrão deste volume é o OpenRouter, pelo controle de custo. O Volume 04 da Biblioteca detalha conta, chave e limites — OpenRouter + Claude Code. Requisito oficial do Hermes: modelo com contexto mínimo de 64K tokens.
hermes setupcd /opt/hermes
sudo docker compose run --rm hermes modelPor segurança, nada aparece enquanto o token é colado. Não é travamento: cole e dê Enter.
O portão desta etapa
hermes chat -q "Responda somente: HERMES OK" -Q --max-turns 1Não configure gateway, cron ou ferramentas enquanto uma conversa simples não estiver estável. Senão você vai depurar dois problemas ao mesmo tempo sem saber qual é qual.
O bot: token abre a porta, ID escolhe quem entra
São dois papéis diferentes e confundi-los é a falha de segurança mais comum deste setup.

Um bot é uma porta com endereço público.
Qualquer pessoa pode encontrar o seu bot e mandar mensagem. O que decide se ela é atendida não é o segredo do nome — é a allowlist. Configure-a antes de contar a alguém que o bot existe.
Envie /newbot, escolha o nome de exibição e um username terminado em bot.
Formato 123456789:ABCdef.... Direto para o gerenciador de senhas, sem print e sem repositório.
No BotFather, /setjoingroups → Disable. Assim ninguém adiciona seu bot a um grupo sem você saber.
Mande qualquer mensagem ao @userinfobot. Ele responde um número como 123456789 — é ele que autoriza, não o @username.
Menu do bot (opcional, mas civilizado)
No BotFather, envie /setcommands, selecione seu bot e cole:
new - Iniciar uma conversa nova
status - Ver modelo e sessão
model - Ver ou trocar o modelo configurado
stop - Interromper a tarefa atual
help - Mostrar os comandos disponíveisQuem tiver esse token controla o bot — e, por ele, fala com um agente que tem terminal na sua VPS. Se vazar: /revoke no BotFather, gere outro, atualize o .env e reinicie o gateway.
Ligar o gateway e fixar a política “somente eu”
O assistente cuida do essencial. O arquivo de segredos é onde você confirma que ele fez o que prometeu.
hermes gateway setupcd /opt/hermes
sudo docker compose run --rm hermes gateway setupA tela fica muda — é o comportamento esperado.
Não escolha acesso aberto em hipótese alguma.
Se a pergunta aparecer, responda que sim.
Confira o arquivo com os próprios olhos
Trilha Rápida: ~/.hermes/.env dentro do contêiner. Trilha Blindada: /opt/hermes/data/.env no host. As linhas precisam estar assim:
TELEGRAM_BOT_TOKEN=SEU_TOKEN_REAL
TELEGRAM_ALLOWED_USERS=SEU_ID_NUMERICO
TELEGRAM_ALLOW_ALL_USERS=false
GATEWAY_ALLOW_ALL_USERS=falsechmod 600 CAMINHO_DO_SEU_ENVNa Trilha Blindada dá para validar sem imprimir o token na tela:
sudo awk -F= '
/^TELEGRAM_BOT_TOKEN=/{t=length($2)>20}
/^TELEGRAM_ALLOWED_USERS=/{u=$2 ~ /^[0-9]+(,[0-9]+)*$/}
/^GATEWAY_ALLOW_ALL_USERS=/{a=tolower($2)}
END {
print "token:", t ? "OK" : "FALTA";
print "allowlist:", u ? "OK" : "FALTA/INVALIDA";
print "acesso global:", (a=="" || a=="false" || a=="0") ? "FECHADO" : "PERIGO";
}' /opt/hermes/data/.envSubir o serviço
hermes gateway run
hermes gateway statuscd /opt/hermes
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=120 hermesUma conta já aprovada por pareamento segue autorizada até ser revogada. Rode hermes pairing list e revogue com hermes pairing revoke telegram ID_NUMERICO qualquer pessoa que você não reconheça.
Seis cercas, porque poder sem cerca é incidente com data marcada
Um agente com terminal numa VPS é poder de verdade. Cinco minutos de configuração cobrem a maior parte do risco.
Allowlist
Só o seu ID numérico. GATEWAY_ALLOW_ALL_USERS nunca vira true.
Aprovação
Comece em manual. Nunca rode o gateway em modo YOLO.
Teto de gasto
Limite por chave no provedor. Modelo caro em laço infinito é fatura surpresa.
Portas fechadas
Nada de expor 8642 ou 9119 na internet pública.
Segredos no lugar
Só no .env com chmod 600. Nunca em skills, memória ou chat.
Um gateway só
Dois processos sobre o mesmo estado geram comportamento fantasma.
Linha de base em seis comandos
hermes config set approvals.mode manual
hermes config set approvals.cron_mode deny
hermes config set approvals.timeout 300
hermes config set security.redact_secrets true
hermes config set security.allow_private_urls false
hermes config set unauthorized_dm_behavior ignoreTrilha Blindada
Prefixe cada linha com sudo docker compose run --rm hermes e recrie o contêiner com sudo docker compose up -d --force-recreate ao terminar.
A identidade operacional
O SOUL.md é onde o agente aprende como se comportar. Regras, não segredos — credencial continua no .env.
# Identidade
Você é Hermes, o agente operacional pessoal de Jaya.
Responda em português do Brasil com clareza, profundidade e objetividade.
# Princípios
- Distinga conversa, recomendação e execução.
- Antes de qualquer ação irreversível, explique alvo, impacto e rollback.
- Nunca revele tokens, senhas, arquivos .env ou credenciais.
- Não invente sucesso: valide com evidência antes de declarar conclusão.
- Se faltar autorização, dado ou critério de aceite, pare e pergunte.
# Operação no Telegram
- Respostas curtas primeiro; detalhes sob demanda.
- Para tarefas longas, informe objetivo, etapa atual e resultado final.
- Nunca habilite YOLO, acesso global ou integração nova sem aprovação explícita.O que permanece proibido
Acesso aberto
Transforma qualquer pessoa que ache o bot em operadora do seu servidor.
Docker socket montado
Equivale, na prática, a entregar root no host.
YOLO permanente
Aprovação é parte do sistema, não enfeite.
Segredo no SOUL ou na memória
Identidade é markdown. Credencial é arquivo protegido.

O que separa “parece pronto” de pronto
Configuração que parece certa não é evidência. Evidência é teste que passou — inclusive o teste que precisa falhar.
9.1 Diagnóstico técnico
docker ps
hermes doctor
sudo ss -lntup
sudo ufw status verboseO ss não deve mostrar o Hermes em 0.0.0.0:8642 nem em 0.0.0.0:9119. Se mostrar, alguma porta foi publicada sem necessidade.
9.2 Os testes pelo Telegram
Peça a alguém de confiança — ou use uma segunda conta sua — para mandar mensagem ao bot. A resposta certa é vácuo total: nem resposta, nem código de pareamento. Se um estranho for atendido, pare o gateway antes de qualquer outra coisa e revise a allowlist.
Só aí a instalação está concluída de verdade — não “quase”.
Operação diária
A colinha que você vai abrir de novo daqui a três semanas, quando tiver esquecido tudo.
| Objetivo | Comando |
|---|---|
| Abrir o chat no terminal | hermes |
| Retomar a última sessão | hermes --continue |
| Trocar de modelo | hermes model · /model dentro do chat |
| Estado do gateway | hermes gateway status |
| Reiniciar o gateway | hermes gateway restart |
| Diagnóstico automático | hermes doctor |
| Ligar e desligar ferramentas | hermes tools |
| Explorar skills prontas | hermes skills browse |
| Tarefas agendadas | hermes cron |
| Quem está pareado | hermes pairing list |
| Validar o config | hermes config check |
| Estado dos contêineres | docker ps |
| Logs — primeiro lugar para olhar | docker logs NOME |
| Reiniciar tudo | docker restart NOME |
O Hermes acorda o modelo quando chega mensagem ou cron. O que gasta é token, não a VPS ligada. O teto continua sendo o limite que você definiu na chave.
Arquivos e áudios
Para receber entregas como anexo no Telegram, peça ao agente para gravar em /opt/data/cache/documents/ e devolver uma linha MEDIA:/opt/data/cache/documents/arquivo.ext. Áudio o Telegram aceita, mas transcrição depende de motor configurado — não confunda “o Telegram recebeu o áudio” com “o modelo consegue transcrevê-lo”.
Backup, atualização e rollback
Atualização sem ponto de retorno não é atualização. É aposta.
Mais hermes backup para levar o agente inteiro.
Se houver regressão aberta que afete o seu uso, adie.
Trilha Rápida: hermes update. Trilha Blindada: troque a tag no compose.yaml, guarde uma cópia do arquivo anterior e recrie.
hermes config check e, se ele pedir, hermes config migrate.
Só então considere a atualização concluída.
Na Trilha Blindada, o diretório /opt/hermes/data contém configuração, token, OAuth, sessões, memória, skills e cron. Trate o backup como cofre — pare o serviço, gere o arquivo com umask 077 e leve uma cópia para fora da VPS. O snapshot do provedor é a segunda camada, não substitui a cópia externa.
Se a versão nova quebrar o gateway, volte primeiro a tag anterior e recrie o contêiner. Só restaure o snapshot se a atualização também tiver migrado ou corrompido dados — e refaça o checklist inteiro depois, inclusive o teste negativo.
Diagnóstico sem adivinhação
Quase todo problema mora numa destas camadas: contêiner, gateway, Telegram ou modelo. Isole uma por vez, nesta ordem.
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Bot não responde nada | Gateway fora do ar ou token errado. | hermes gateway status, logs do contêiner e gateway setup de novo. |
| “Unauthorized” para você | ID errado ou salvo como @username. | Confirme o ID numérico no .env e reinicie. |
| Outra pessoa consegue usar | Allowlist aberta ou pareamento indevido. | Pare o gateway, confirme GATEWAY_ALLOW_ALL_USERS=false, revise pairing list. |
| Responde “oi” mas falha nas tarefas | Modelo, crédito ou OAuth expirado. | Troque o modelo e confira saldo e limite da chave. |
| Parou depois de reboot | Contêiner não subiu sozinho. | docker ps e docker update --restart unless-stopped NOME. |
| Gateway morre sozinho · RAM explode | Regressão de memória relatada na v0.20.0. | Fixe a v0.19.1 ou limite a memória do contêiner e acompanhe a issue. |
| Loop de reinício | Config inválida ou permissão do volume. | Leia os logs, rode docker compose config e doctor. |
| Comando fica aguardando | Aprovação manual pendente. | Aprove ou negue no Telegram; o timeout nega sozinho. |
| Ignora mensagens em grupo | Privacy mode do Telegram — comportamento esperado aqui. | Mantenha assim até existir caso de uso e allowlist de grupo. |
| Disco enchendo | Sessões, cache ou logs. | docker system df e du -h -d 2 na pasta de dados. Não apague antes do backup. |
| Não sabe o que está errado | — | hermes doctor, depois docker logs e o log do gateway. |
O contêiner está de pé? → o gateway está de pé? → o que dizem os logs? → o CLI responde? Um nível por vez isola se o problema é infra, gateway, Telegram ou modelo.
Extensão opcional: Desktop pela Tailscale
O painel visual do Hermes no seu computador, alcançável só pela sua rede privada. Só faça isto depois que o Telegram estiver estável e com backup.
O Telegram continua por long polling, sem porta nenhuma. O Desktop aponta para a porta 9119, vinculada exclusivamente ao IP Tailscale da VPS e protegida por duas barreiras: a política da tailnet e a autenticação do próprio Hermes.
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --hostname=hermes-vps
tailscale ip -4
tailscale statusDepois marque a VPS como tag:hermes-server e o notebook como tag:hermes-client, e restrinja o acesso no painel de Access controls:
{
"tagOwners": {
"tag:hermes-server": ["SEU_EMAIL_DE_OWNER"],
"tag:hermes-client": ["SEU_EMAIL_DE_OWNER"]
},
"grants": [
{
"src": ["tag:hermes-client"],
"dst": ["tag:hermes-server"],
"ip": ["tcp:9119"]
}
]
}Manter uma regra ampla — src: ["*"], dst: ["*"] — junto do Grant acima anula o isolamento que você acabou de configurar. Salve só depois que o validador do painel aprovar o JSON.
Antes de ligar
2FA na conta que autentica a Tailscale, Require device approval ligado e revisão da lista de máquinas. Sem isso, o resto é teatro.
Ao validar
A 9119 tem que aparecer no IP 100.x.x.x — nunca em 0.0.0.0 nem no IP público. Com a Tailscale desconectada, a URL precisa deixar de responder.
Mantenha o Desktop num arquivo Compose separado. Desligá-lo não afeta o Telegram, porque o serviço principal não depende dele. O token do BotFather, aliás, não passa pela Tailscale: é outro canal, com controles próprios.
Expandir sem desmontar a base
Complexidade não é maturidade. Uma fase só entra em produção quando a anterior está estável, observável e recuperável.
| Fase | O que entra | Portão de saída |
|---|---|---|
| 1 | Telegram privado + um modelo | Checklist completo funcionando por sete dias. |
| 2 | SOUL, memória e skills aprovadas | Backup e rollback testados de verdade. |
| 3 | Cron e briefings automáticos | Custos, logs e entregas monitorados. |
| 4 | Desktop pela Tailscale | 9119 só no IP da tailnet; Grant e autenticação validados. |
| 5 | Uma integração externa por vez | Credencial mínima, leitura confirmada e rollback pronto. |
| 6 | WhatsApp, workers e subagentes | Governança, evidência, limites e handoff humano. |
O portão de qualquer integração nova
Checklist de conclusão
Se todas as linhas abaixo forem verdade, a Fase 1 está fechada — e você pode desligar o computador sem desligar o agente.
Base técnica
Conteúdo consolidado em 11 de agosto de 2026 a partir de dois manuais internos com base técnica verificada em 10/08/2026. Versões, subcomandos e telas podem mudar.
Este volume nasceu da fusão de dois manuais que divergiam em três pontos: caminho de instalação, provedor recomendado e local do arquivo de segredos. As divergências não foram apagadas — viraram as duas trilhas do capítulo 01 e a tabela de rotas do capítulo 05. Onde a documentação oficial contradizia o material de aula, a documentação oficial prevaleceu.

