⚙️ Setup do Zero

VPS é uma máquina virtual dedicada na nuvem com IP público fixo, ligada 24 horas. Diferente do laptop, ela não dorme, não cai quando você fecha a tampa, e não depende do seu Wi-Fi residencial.

Crons só são confiáveis em máquina sempre ligada. Telegram precisa do gateway acessível continuamente. Sua máquina pessoal não foi feita pra isso. KVM 2 da Hostinger custa o equivalente a um Spotify Premium e cabe múltiplos agentes.

VPS = Virtual Private Server. KVM = tipo de virtualização (kernel-level, mais isolado que LXC). NVMe = disco rápido. Banda mensal = limite de transferência (8TB no KVM 2 é generoso para Hermes).

Hostinger tem o melhor onboarding pra brasileiro (preço em real, suporte PT-BR, painel simples). Hetzner é o mais barato pro porte. DigitalOcean tem ecossistema rico de tutoriais. Oracle Always Free dá micro-VPS gratuito.

A escolha errada vira atrito por meses. Hostinger é o caminho recomendado pra primeiro Hermes — instalação simples, NVMe rápido e desconto de boas-vindas significativo. Hetzner exige mais autonomia técnica.

Hostinger: $8,99/mês com desconto, $14,99 renovação. Hetzner: ~€4 por equivalente. DO: $12+/mês. Oracle Free: ARM64 com 24GB RAM gratuitos, mas burocracia de cadastro alta.

KVM 2 da Hostinger oferece 2 vCPUs, 8 GB RAM, 100 GB NVMe e 8 TB de banda. Ele cabe Hermes + Docker + um par de skills pesadas (browser automation, vision) sem suar.

Subdimensionar (KVM 1, 4GB) faz Docker engasgar quando você pede coisa que carrega Chromium. Superdimensionar (KVM 4) só vale se você for rodar múltiplos perfis ou kanban multi-agente.

Tabela: KVM 1 ($6,49) é OK pra teste; KVM 2 ($8,99) é o sweet-spot; KVM 4 ($12,99) pra múltiplos agentes; KVM 8 ($25,99) para Kanban com vários workers paralelos.

Ubuntu 24.04 LTS é o padrão recomendado: suporte até 2029, comunidade gigante, todos os tutoriais usam. Escolha um hostname memorável (ex: hermes-pessoal), datacenter próximo (São Paulo se possível), e ative backup diário.

Distros menos populares (CentOS, Alpine) têm pegadinhas com Docker, NodeJS e Python. LTS = atualizações de segurança garantidas. Backup automático te salva quando você quebra algo às 23h de uma sexta.

LTS = Long Term Support (5 anos). Hostname aparece no prompt — facilita identificar terminal. Datacenter próximo reduz latência do SSH e do Telegram. Backup Hostinger ~$1/mês a mais, vale cada centavo.

Após o servidor subir, conecte via ssh root@SEU_IP. Atualize o sistema com apt update && apt upgrade -y. Crie um usuário não-root, instale ufw e habilite firewall mínimo (22 SSH, 443 HTTPS).

Rodar tudo como root é receita pra desastre. Um comando mal copiado e você apagou o /etc inteiro. Usuário separado limita estrago. ufw bloqueia portas que você não usa, reduzindo superfície de ataque.

adduser hermes + usermod -aG sudo hermes cria usuário com escalonamento. ufw default deny incoming + ufw allow 22 + ufw enable ativa o firewall.

Trocar autenticação por senha por chave SSH (ssh-keygen + ssh-copy-id), desabilitar login root direto, instalar fail2ban (bloqueia IPs com tentativas de força bruta).

VPS público leva milhares de tentativas de login por dia. Sem hardening, é só questão de tempo. Com chave + fail2ban + ufw, o servidor fica praticamente intocável pra brute-force.

Editar /etc/ssh/sshd_config: PasswordAuthentication no e PermitRootLogin no. Reiniciar com systemctl restart sshd. Antes de fechar a sessão, abra outro terminal e teste login com chave — se quebrar, você ainda tem acesso.

Docker isola o Hermes em um container com seu próprio filesystem, suas próprias dependências Python, seu próprio .env. Você pode rodar 3 Hermes em paralelo (pessoal, marketing, financeiro) na mesma VPS sem conflito.

Sem Docker, atualizar Python ou bibliotecas vira drama. Skills que dependem de versões específicas brigam. Quando algo falha, você não sabe se foi do sistema ou do agente. Container é a borda limpa.

Imagem = template. Container = instância rodando. Volume = pasta persistente fora do container. ~/.hermes tem que ser volume, senão você perde memória ao recriar o container.

A forma certa: curl -fsSL https://get.docker.com | sh. Esse script é mantido pela própria Docker e instala engine + compose plugin atualizados. Hostinger também oferece "Docker app" one-click no painel.

Pacote do Ubuntu (apt install docker.io) costuma estar atrasado. Docker Compose v1 (em Python) está descontinuado — só funciona o v2 (plugin Go). Pegar o errado custa horas debugando "command not found".

Após instalar: usermod -aG docker hermes pra rodar sem sudo. Logout + login. Teste com docker run hello-world. Compose v2: docker compose (sem hífen), não docker-compose.

Arquivo docker-compose.yml declara o serviço hermes: imagem oficial, volume ~/.hermes:/root/.hermes (persistência), env_file apontando pro .env, e restart: unless-stopped para subir sozinho após reboot.

Sem volume, ao recriar o container você perde toda a memória, skills, sessões. Sem restart policy, depois de uma queda de energia o agente não volta sozinho. Sem env_file, secrets viram strings hardcoded — ruim de versionar.

Volume bind mount = pasta do host aparece dentro do container. env_file: .env injeta variáveis. TZ=America/Sao_Paulo ajusta timezone. tty: true deixa o agente interativo via docker exec.

Comando: docker compose up -d sobe em background. docker logs -f hermes mostra o log em tempo real. docker exec -it hermes hermes entra na CLI interativa do agente.

A primeira subida é onde quase tudo dá errado: token errado, volume com permissão errada, .env não montado. Saber ler logs e identificar o sintoma ajuda a corrigir em minutos em vez de horas.

up -d = detached. logs -f = follow. exec -it = interactive + tty. Erros comuns: "permission denied" no volume → ajustar uid/gid; "missing API key" → .env errado.

Os 5 comandos que você vai usar 90% do tempo: docker compose up -d, docker compose restart, docker exec -it hermes hermes, docker exec -it hermes hermes config set X=valor, docker logs hermes --tail 100.

Decorar esses 5 comandos elimina dependência de tutorial. Você vira autônomo pra debugar e ajustar configurações em segundos. hermes config set escreve no .env do container — não confundir com .env do host.

Após config set, sempre docker compose restart para o agente reler. docker compose pull baixa imagem nova. docker compose down para tudo (preserva volumes).

Fluxo seguro: docker compose pull baixa nova imagem, docker compose up -d recria container já com a nova versão. O volume ~/.hermes permanece intocado — memória, skills, state.db tudo lá.

Hermes lança versões frequentes (v0.13.0 saiu há 3 dias). Você precisa atualizar com confiança. Confundir down -v (apaga volume) com down (preserva) destrói meses de trabalho. Decorar é seguro.

Antes de qualquer atualização: backup do volume (tar czf hermes-backup.tgz ~/.hermes). docker compose down = para; down -v = para + apaga volumes. NUNCA usar -v num agente em produção.

Codex OAuth usa sua conta ChatGPT (Plus $20 ou Pro $200) como provedor. Login via browser, sem API key. Modelo padrão: gpt-5.3-codex com vision. Tudo dentro do plano fixo da OpenAI.

É a opção mais barata pra uso intenso. Pela API, 10 conversas longas por dia passam fácil de $100/mês. Pelo Plus, mesmo uso fica em $20 fixos. Pro libera o3, o4-pro e GPT-5 com limites altos.

Configurar com provider: "codex" no config.yaml. Hermes pede pra abrir URL no browser, você loga, ele captura o token. Limitação: rate limits do plano ChatGPT — não é "ilimitado de verdade".

OpenRouter é um agregador: você bota crédito, escolhe qualquer modelo (Claude, Gemini, DeepSeek, Grok, GPT) e paga por token. openrouter/owl-alpha é grátis. Gemini Flash custa ~$0,075/1M tokens.

Permite trocar modelo por tarefa. Compressão de contexto pode usar Gemini Flash (barato). Conversa principal usa Claude. Watchdog pode usar owl-alpha (grátis). Você ajusta cada slot ao orçamento.

Configurar com OPENROUTER_API_KEY + provider: "openrouter". Modelos novos no v0.13.0: deepseek/deepseek-v4-pro, x-ai/grok-4.3, tencent/hy3-preview.

Claude Opus / Sonnet via API direta da Anthropic ou via GMI (revendedor). O modelo mencionado nos exemplos do Hermes v0.13.0 é claude-opus-4.6. Excelente em código complexo e raciocínio longo.

Quando a tarefa é crítica (review de código, escrita longa, planejamento estratégico), Claude tem qualidade superior. Vale o custo extra para uso pontual. Para volume alto, Codex+OpenRouter é mais econômico.

Anthropic não está nativamente sem enforcement no Hermes — modelo confiado nativamente. Tools usadas com confiança nativa. Use GMI para faturamento centralizado se ainda não tem conta Anthropic.

MiniMax OAuth: login browser, sem API key (similar a Codex). Nous Portal: hermes auth + provider: "nous". Local: qualquer endpoint OpenAI-compatible (Ollama, LM Studio, vLLM) com base_url: "http://localhost:1234/v1".

Cenários de privacidade extrema (dados sensíveis nunca saem da rede), uso desconectado, custo zero pra volume infinito (após hardware). Mac Mini M2 com Qwen ou LLaMA roda 90% das tarefas pessoais.

Modelos sem enforcement (confiados): Claude, DeepSeek, Qwen, LLaMA. Modelos com enforcement automático: gpt, codex, gemini, gemma, grok. Local exige hardware: 16GB+ pra modelo de 7B, 32GB+ pra 13B.

Top picks da release v0.13.0: gpt-5.3-codex (padrão Codex OAuth), deepseek/deepseek-v4-pro (raciocínio forte e barato), x-ai/grok-4.3 (resposta longa), claude-opus-4.6 (qualidade premium), MiniMax-M2.7 (sem API key).

O modelo certo na tarefa certa muda 10x a experiência. Codex pra geral, DeepSeek pra raciocínio matemático, Claude pra texto longo, Gemini Flash pra compressão. Misturar é o jeito otimizado.

Vision: gpt-5.3-codex e Claude Opus suportam. Tool use enforcement: gpt/codex/gemini/gemma/grok recebem reforço automático; Claude/DeepSeek/Qwen/LLaMA são confiados nativamente.

Árvore de decisão: já tem ChatGPT Plus? Codex OAuth. Quer flexibilidade entre modelos? OpenRouter. Privacidade extrema? Local via Ollama. Tarefas top-quality? Anthropic. Volume alto barato? OpenRouter + DeepSeek/Gemini.

Sem critério, você fica trocando provedor toda hora. Com critério, você escolhe uma vez e otimiza ao longo do tempo. Trocar é trivial (uma linha em config.yaml), mas pular sem razão queima energia.

Recomendação inicial: Codex OAuth como principal + OpenRouter como fallback (Gemini Flash pra compressão). Privacidade alta? Adiciona endpoint local. Migração entre provedores: zero trabalho — só edita config.yaml + restart.

Telegram é a mensageria com menor fricção pra criar bot. BotFather é um bot oficial do próprio Telegram que cria outros bots em 30 segundos via comandos no chat. Sem developer portal, sem aprovação.

Discord exige cadastro de aplicação. WhatsApp passa por gateway pago (Whapi) ou Meta Business Manager. iMessage exige BlueBubbles num Mac. Telegram resolve em 5 minutos — você valida o setup completo antes de complicar.

Hermes suporta 20+ plataformas, mas Telegram é o caminho de menor resistência. Voice notes, comandos slash, anexos, stickers — tudo funciona. App tem cliente desktop e mobile sólido.

Abra o Telegram, busque @BotFather. Envie /newbot. Ele pergunta o nome (display) e o username (terminado em "bot"). Devolve um token tipo 1234567890:AAH... — esse é o segredo do seu bot.

O token é a credencial completa do bot — quem tiver ele controla. Tratar como senha é crítico. Nunca cole em chat público, nunca commite em repositório. Use hermes config set TELEGRAM_TOKEN xxx dentro do container.

Username precisa ser único globalmente no Telegram. Customizações úteis no BotFather: /setdescription, /setuserpic, /setcommands (lista de comandos slash). Pode revogar token com /revoke se vazar.

Hermes precisa saber quem está autorizado a falar com ele. Não basta ter o bot — qualquer um que descubra o username poderia mandar mensagem. Usar @userinfobot retorna seu numerical user ID (ex: 123456789).

Sem authorized users configurado, o bot ou aceita qualquer um (perigoso) ou ignora você (frustrante). User ID é a forma estável de autorizar — username pode mudar, ID não.

User ID é numérico, único, permanente. Pode autorizar múltiplos IDs se compartilha o agente com cônjuge/sócio. Para grupos, o ID começa com sinal negativo (-100...).

Dentro do container: hermes gateway setup abre um wizard. Cole o token do bot, cole seu user ID, escolha o home channel (canal padrão para entregas de cron). Ele salva em ~/.hermes/.env e ~/.hermes/config.yaml.

Tentar editar arquivos manualmente costuma quebrar formatação. O wizard valida cada passo e testa conexão antes de salvar. hermes gateway start sobe o gateway depois.

Home channel = canal/chat padrão pra entregas automáticas (crons). Pode ser DM com você ou grupo dedicado. Variáveis: TELEGRAM_TOKEN, TELEGRAM_HOME_CHANNEL, TELEGRAM_AUTHORIZED_USERS.

Mande "Olá" pro bot. Resposta esperada: o agente responde apresentando-se. Se não responder: hermes gateway status mostra estado, tail -f ~/.hermes/logs/gateway.log mostra erro em tempo real.

Primeira mensagem é o teste mais importante. Se passar, todo o setup está OK. Se falhar, o erro nos logs é objetivo (token errado, usuário não autorizado, sem internet). Resolver é literalmente seguir o erro.

Erros frequentes: "401 Unauthorized" = token errado; "user not authorized" = ID não está em TELEGRAM_AUTHORIZED_USERS; "connection timeout" = firewall bloqueando saída do container pra api.telegram.org.

Voice notes são entendidas (Telegram envia áudio, Hermes transcreve e responde). Comandos slash /cron, /usage, /compress, /skills funcionam direto. Permissões: cada ação sensível pergunta allow once / session / always.

Mensagem de voz acelera muito comunicação em movimento (no carro, andando). Slash commands viram seu controle remoto: ver crons agendados, comprimir contexto, listar skills, ver gasto de tokens.

Permissões persistem em ~/.hermes/permissions.json. Always só pra coisas confiáveis (git push em repo seu). Session pra exploração. Once pra ação destrutiva única.

GitHub vira o backup oficial do seu agente: SKILL.md, MEMORY.md, USER.md, SOUL.md, config.yaml versionados em repo privado. Se o VPS pegar fogo, você restaura tudo em outro servidor em minutos.

Hermes constrói valor com o tempo: meses de feedback, dezenas de skills criadas, memória rica. Perder isso por uma falha de hardware é trauma. Git resolve com 0 esforço operacional após setup.

Repo privado = ninguém vê. Skills viajam entre máquinas via clone. Múltiplos agentes apontam pro mesmo repo de skills compartilhadas. Você pode até montar o repo no ~/.hermes/skills via git clone.

No GitHub: Settings → Developer settings → Personal access tokens. Fine-grained PAT permite limitar a repos específicos com escopos cirúrgicos (apenas push/pull, sem delete). Classic PAT é mais antigo, escopos amplos.

Princípio do menor privilégio. Token classic com repo permite apagar todos os seus repos se vazar. Fine-grained limitado a 1 repo + permissões mínimas reduz blast radius drasticamente.

Validade do token: defina expiração (90 dias é razoável). Escopos sugeridos para Hermes: Contents: Read and write, Metadata: Read. Nada além disso. Quando expirar, gere novo e atualize.

Forma certa: docker exec -it hermes hermes config set GITHUB_TOKEN ghp_xxx. Isso escreve no ~/.hermes/.env dentro do container, com auto-redação aplicada nos logs.

Tokens colados no chat acabam no histórico SQLite, em logs sem redação, em sessões pesquisáveis. config set é o único caminho que coloca em local seguro com proteção de log.

Hermes tem auto-redação de secrets em ~/.hermes/logs/errors.log. config set é o único método garantido a passar pela redação. Cola direto no chat = logs em texto puro.

Antes de qualquer git add ., crie .gitignore com: .env, .env.*, state.db, state.db-*, logs/, *.key, *.pem, permissions.json.

Commit acidental de .env é o erro mais comum em VPS pessoal. Se foi pra repo público, o token vaza em segundos (bots de scraping). Mesmo em privado, history fica permanente — quem entrar no repo vê.

Se já commitou .env: revogue o token IMEDIATAMENTE no GitHub e regere. git filter-repo ou BFG removem do histórico, mas o segredo já vazou. Prevenção > remediação.

Com token configurado, mande no Telegram: "Configure este agente como repo privado no GitHub. Crie .gitignore bloqueando .env, state.db, logs e permissions.json. Faça primeiro commit com SKILL, MEMORY, USER, SOUL, config.yaml."

Aplicação direta da mentalidade da T1.2: pergunte ao próprio Hermes. A skill github bundled já sabe criar repo, gerar gitignore correto e fazer push inicial — você não precisa decorar comandos git.

Antes de aprovar a ação destrutiva (push), revise o .gitignore que ele propôs. Se faltar algo, corrija. Marca always allow só depois que validar funcionando.

Existem DOIS .env: o do host (~/hermes-deploy/.env, lido pelo docker compose) e o do container (/root/.hermes/.env, lido pelo Hermes). O agente lê o segundo. Editar com docker exec -it hermes nano /root/.hermes/.env.

Editar o errado = mudança não tem efeito. Você restarta achando que vai pegar nova chave, mas o agente continua usando a antiga. Confundir os dois é fonte clássica de horas perdidas debugando.

Após editar o .env do container: docker compose restart. Para deletar uma chave: editar e remover a linha. hermes config get GITHUB_TOKEN mostra o valor atual (com mask) pra confirmar qual está ativo.

Backup diário pro GitHub é o cron de menor risco e maior valor. Ele só faz git add . && git commit -m "..." && git push dentro de ~/.hermes. Não toca em sistema, não chama API externa de risco, não gasta tokens caros.

É a forma certa de testar o sistema de cron com confiança. Se quebrar, nada de grave acontece. Se funcionar, você ganha resilência permanente. É o "Hello World" pragmático do Hermes.

Princípio: comece pelo cron mais útil e mais seguro. Crons ambiciosos no dia 1 (responder email, postar conteúdo) são frágeis e perigosos. Backup é trivial e produtivo.

No chat do Telegram: /cron add "every 1d at 00:00" "Faça commit e push das mudanças do agente pro GitHub". O Hermes interpreta linguagem natural, gera o job e confirma agendamento.

Forma mais rápida de criar cron. Você não precisa decorar sintaxe cron clássica (0 0 * * *). Linguagem natural é traduzida pra estrutura interna do Hermes (jobs.json).

Aceita: "every 30m", "every 2h", "every 1d at 09:00", "every monday at 08:00", "weekly". /cron list mostra todos os jobs. /cron remove ID apaga.

Equivalente CLI: hermes cron create "every 1d at 00:00" "Backup do agente" --workdir /root/.hermes. Executa dentro do container. Mais explícito, ideal pra script idempotente de provisioning.

Quando você for replicar o setup em outro VPS, comandos CLI são reproduzíveis. Pode versionar como bootstrap.sh. Telegram é melhor pra exploração; CLI é melhor pra automação.

Flags principais: --workdir (define cwd, carrega AGENTS.md dali), --no-agent (script puro sem LLM), --deliver telegram (canal), --skill nome (injeta skill). --name backup-diario facilita identificar.

Container Docker roda em UTC por padrão. "every 1d at 00:00" dispara à meia-noite UTC, que é 21:00 em Brasília (UTC-3). Para corrigir: TZ=America/Sao_Paulo nas env vars do container OU timezone: "America/Sao_Paulo" em config.yaml.

Cron rodando 3 horas antes do esperado é confusão garantida. "Backup às 00:00" que dispara às 21:00 do dia anterior bagunça percepção e logs. Configurar timezone certo no início economiza muito retrabalho.

IANA timezone string: America/Sao_Paulo, America/Bahia, Europe/Lisbon. Após configurar, restart do container e checar com docker exec hermes date.

Na primeira execução, Hermes vai pedir permissão pra rodar git commit e git push. Marque always allow — é uma ação segura, recorrente, com escopo travado pelo PAT fine-grained.

Sem always allow, todo cron diário trava esperando você responder o prompt — defeitando o propósito de ser automático. Marcar uma vez resolve permanentemente.

Persistência em ~/.hermes/permissions.json. Pode listar permissões aprovadas com hermes permissions list. Revogar uma com hermes permissions revoke ID. Auditar regularmente.

Após criar: /cron list mostra job + next_run_at. No primeiro disparo, Hermes responde no canal home com resultado. Conferir no GitHub: novo commit aparece com mensagem do agente.

"Achar que rodou" é diferente de "ter rodado". Confirmar com fato — commit visível no GitHub — fecha o loop. Se não rodou, logs em ~/.hermes/logs/cron.log mostram exatamente o que falhou.

Lock file ~/.hermes/cron/.tick.lock previne double-run. ~/.hermes/cron/jobs.json tem todo o estado. Histórico de execuções fica na sessão SQLite — pesquisável via session_search.