Configurando o ambiente Hermes | TRIAD

📋 Pré-requisitos

Antes de instalar o Hermes, confirme três coisas: sistema operacional compatível, Node.js 20+ e uma conta Anthropic com API key ativa. Pular essa verificação é a causa #1 de instalações quebradas.

O que é

O Hermes Agent é um runtime CLI que orquestra agentes do Triad localmente. Roda em Linux, macOS e Windows (via WSL2), exige Node.js 20.x ou superior e uma ANTHROPIC_API_KEY válida para se conectar aos modelos Claude.

🔍 Verifique o que você já tem

# Versão do Node — precisa ser >= 20.x

node --version

# v20.11.1

# Versão do npm — precisa ser >= 10.x

npm --version

# 10.2.4

# Sistema operacional

uname -a

✓ Ambiente válido

✓Node.js 20.x ou superior (LTS recomendado)
✓npm 10.x via gerenciador oficial
✓API key Anthropic (formato sk-ant-...)
✓Permissão de escrita em ~/

✗ Configurações que quebram

✗Node.js 18.x ou inferior (faltam APIs)
✗npm instalado via sudo (permissões erradas)
✗Windows nativo sem WSL2
✗API key expirada ou sem créditos

💡 Dica primária

Use nvm para gerenciar versões do Node — assim você troca entre projetos sem conflito. Evite sudo npm install a qualquer custo: ele cria arquivos com owner errado em ~/.npm e quebra futuras instalações globais.

🔑 Conceitos-chave

Node 20 LTS

Versão mínima — APIs de fetch nativo e streams modernos são exigidas

API key como segredo

Nunca commite no Git — sempre via variável de ambiente

WSL2 no Windows

Hermes assume um shell POSIX — Windows nativo não é suportado

Permissões em ~/

O Hermes cria ~/.hermes/ — exige escrita no home do usuário

📦 Instalação do Hermes Agent

A instalação acontece em duas etapas: um comando global do npm e um setup wizard interativo que prepara o ambiente local. O wizard valida tudo antes de finalizar.

O que é

O hermes-agent é o pacote npm que instala o binário hermes no PATH. Após a instalação, hermes init é o wizard que cria a estrutura ~/.hermes/, valida a API key, registra o usuário e baixa as skills padrão.

🚀 Instalação global

# Instala o binário global

npm install -g hermes-agent

# Confirma a instalação

hermes --version

# hermes-agent 1.4.2

# Inicia o setup wizard

hermes init

🧙 O que o setup wizard faz

1. Detecta o shell ativo (zsh, bash, fish) para configurar PATH e env vars no rc correto.

2. Cria ~/.hermes/ com subdiretórios memory/, skills/, jobs/ e logs/.

3. Pede a API key e faz uma chamada de validação contra a API Anthropic.

4. Baixa as skills padrão do registry oficial — research, code, review.

5. Roda um smoke test de fim a fim — se passar, a instalação está confirmada.

🔑 Conceitos-chave

Instalação global vs local

Hermes é um CLI — global (-g) é o caminho correto, nunca dentro de projetos

Setup wizard idempotente

Pode rodar hermes init múltiplas vezes — só corrige o que estiver faltando

Validação de API key embutida

O wizard só prossegue se a chave responder com 200 na rota /v1/models

Skills padrão pré-instaladas

research, code e review já vêm prontas — você pode adicionar customizadas depois

⚙️ Configuração inicial

Depois do hermes init, três configurações precisam estar corretas para o agente funcionar de verdade: a API key persistente no shell, a estrutura de diretórios e as permissões de arquivo.

O que é

A configuração inicial define onde o Hermes guarda dados (~/.hermes/), como acessa a Anthropic (ANTHROPIC_API_KEY via env) e quais permissões os arquivos têm (600 para o config, 700 para o diretório). É o tripé que mantém o sistema seguro e funcional.

🔐 Configurando a API key no shell

# Adicione ao final do ~/.zshrc (ou ~/.bashrc)

export ANTHROPIC_API_KEY=sk-ant-api03-...

# Recarregue o shell

source ~/.zshrc

# Confirme que está no ambiente

echo $ANTHROPIC_API_KEY | head -c 20

# sk-ant-api03-XXXXXX

📁 Estrutura de diretórios

mkdir -p ~/.hermes/{memory,skills,jobs,logs}

~/.hermes/

├── config.json # configuração principal (chmod 600)

├── memory/ # estado persistente entre runs

├── skills/ # pacotes de skills instaladas

├── jobs/ # histórico de tarefas executadas

└── logs/ # logs estruturados em JSONL

# Permissões seguras

chmod 700 ~/.hermes

chmod 600 ~/.hermes/config.json

🧩 Três camadas de configuração

•Env vars — segredos (API keys, tokens) ficam aqui. Nunca em arquivo.

•~/.hermes/config.json — preferências do usuário (modelo padrão, timeouts, telemetria).

•.hermes.json no projeto — overrides por projeto, commitáveis no Git sem expor segredos.

💡 Dica primária

Se você usa 1Password CLI ou direnv, integre a API key dali em vez de hardcodar no ~/.zshrc. Assim a chave nunca toca o disco em texto plano e rotação fica trivial.

🔑 Conceitos-chave

Segredos via env

API key em variável de ambiente, nunca em config.json commitável

Permissões 700/600

Diretório ~/.hermes só para o user; config.json só leitura/escrita do owner

Config em camadas

Env → user config → project config — o último sobrescreve

Estrutura de diretórios fixa

memory/, skills/, jobs/, logs/ — Hermes assume essa hierarquia

✅ Primeiro teste

Antes de pedir ao Hermes qualquer tarefa real, rode o smoke test pós-instalação: dois comandos curtos confirmam que o binário está no PATH, a API key funciona e o pipeline de jobs está vivo.

O que é

O smoke test é a sequência mínima de comandos que prova que a instalação funciona ponta a ponta: hermes ping testa conectividade com a Anthropic, hermes status mostra o estado do daemon, das skills carregadas e do último job executado.

🏓 Comando 1: hermes ping

hermes ping

✓ Binário detectado: /usr/local/bin/hermes

✓ Config carregada: ~/.hermes/config.json

✓ API key válida (sk-ant-***...***ZP4Q)

✓ Latência Anthropic: 187ms

✓ Modelo padrão: claude-sonnet-4-5

📊 Comando 2: hermes status

hermes status

Daemon ......... running (pid 38291)

Skills ......... 3 loaded (research, code, review)

Memory ......... 0 entries

Jobs ........... 0 active, 0 historic

Last error ..... none

Uptime ......... 00:00:14

🧪 Job de teste real

Para confirmar o pipeline completo, envie um job trivial:

hermes run "diga apenas: ambiente operacional"

# job_id: hms_01HXY...

# status: completed (1.2s)

ambiente operacional

🔑 Conceitos-chave

Smoke test mínimo

Ping + status + um job trivial — três comandos cobrem o pipeline

Latência como sinal

Latência acima de 1s no ping indica rede ou rate limit

Skills carregadas

status mostra quantas skills o daemon registrou — 0 indica problema

Job ID rastreável

Todo hermes run emite um ID — usado para auditar e re-executar

🖥️ O dashboard do Hermes

O Hermes expõe um dashboard local chamado Pantheon — uma interface web em http://localhost:7777 que mostra histórico de jobs, status das skills, custo acumulado e logs ao vivo. É o painel de controle para inspeção.

O que é

Pantheon é a UI web embutida no Hermes que serve em localhost:7777 e oferece quatro painéis: Jobs (histórico e status), Skills (instaladas e versão), Memory (estado persistente) e Logs (stream estruturado). É read-only por design — comandos de mutação continuam pelo CLI.

🚪 Subindo o dashboard

hermes dashboard

✓ Pantheon UI: http://localhost:7777

✓ WebSocket logs: ws://localhost:7778

# Abra no navegador — Ctrl+C aqui encerra.

🏛️ Os quatro painéis do Pantheon

•Jobs — lista cronológica com job_id, prompt, status (running/done/failed), duração e custo em USD.

•Skills — pacotes instalados, versão semântica, última atualização e botão para inspecionar manifest.

•Memory — entradas persistentes (chave/valor) e tamanho em bytes. Útil para depurar drift de estado.

•Logs — stream ao vivo via WebSocket; cada linha é JSON estruturado com level, ts, source e payload.

🔎 Inspecionando um job pelo CLI

hermes job show hms_01HXY...

id ............ hms_01HXY...

prompt ........ "diga apenas: ambiente operacional"

status ........ completed

model ......... claude-sonnet-4-5

tokens ........ 14 in / 4 out

cost .......... $0.00012

duration ...... 1.184s

🔑 Conceitos-chave

Pantheon como UI read-only

Dashboard inspeciona; mutações continuam pelo CLI para evitar drift

Custo por job visível

Cada execução mostra tokens e USD — base para auditoria de gasto

Logs estruturados em JSONL

Cada linha é JSON parseável — facilita grep, jq e ingestão em observability

localhost:7777 fechado por padrão

Bind apenas em 127.0.0.1 — para expor, configure proxy reverso explícito

🔗 Conectando Claude Code ao Hermes

O Claude Code pode delegar tarefas pesadas ao Hermes via uma ponte chamada hermes-bridge. O CC continua sendo seu pair-programmer no terminal — o Hermes executa em background trabalhos de longa duração, paralelos ou que exigem skills específicas.

O que é

O hermes-bridge é uma flag do Claude Code que registra o daemon Hermes como provedor de jobs assíncronos. Com a ponte ativa, o CC ganha um novo tool delegate_to_hermes(task, skill) — útil para refactors longos, varreduras de codebase ou análises que ultrapassam o context window de uma sessão.

🌉 Ativando a ponte

# Sessão CC com ponte ativa

claude code --hermes-bridge

✓ Hermes daemon detectado (pid 38291)

✓ Bridge ativa em ws://localhost:7778

✓ Tool registrado: delegate_to_hermes

# Persistir como padrão

echo 'alias cc="claude code --hermes-bridge"' >> ~/.zshrc

🎯 Quando delegar ao Hermes

•Tarefas >30 minutos — refactors de monorepo, migrações de versão, testes massivos.

•Trabalho paralelo — quando você quer 3–5 ângulos rodando ao mesmo tempo sem travar a sessão CC.

•Skill especializada — research profundo, vetorização de codebase, auditoria de segurança com tools dedicadas.

•Contextos grandes — quando o input ultrapassa o orçamento da sessão atual e precisa de chunking.

✓ Bom uso da ponte

✓"Hermes, audita os 200 arquivos de src/api/"
✓"Hermes, roda 4 estratégias de migração em paralelo"
✓"Hermes, mapeia dependências entre módulos"

✗ Delegar errado

✗"Hermes, renomeia esta variável" (CC resolve em 2s)
✗Delegar com input ambíguo — gera job inútil
✗Delegar sem critério de sucesso (vira loop infinito)

🔑 Conceitos-chave

Bridge via WebSocket

CC e Hermes conversam por ws://localhost:7778 — sem polling

delegate_to_hermes como tool

Aparece no toolbelt do CC — só dispara quando o modelo decide delegar

Async por design

A sessão CC não trava esperando — recebe o job_id e segue conversando

Critério de sucesso obrigatório

Job sem critério vira loop — sempre passe condições testáveis

🩺 Verificação de saúde

Antes de avançar para o próximo módulo, rode hermes doctor — o diagnóstico oficial que audita 12 checks de instalação, configuração e conectividade e devolve um relatório com correções automáticas quando possível.

O que é

O hermes doctor é a ferramenta de auto-diagnóstico do Hermes. Executa 12 verificações categorizadas em quatro grupos (Sistema, Config, Rede, Skills) e emite um relatório com status PASS, WARN ou FAIL para cada item — com sugestão de correção quando aplicável.

🩺 Saída de hermes doctor

hermes doctor

━━━ Sistema ━━━

PASS Node.js >= 20.x (v20.11.1)

PASS Shell POSIX detectado (zsh)

PASS Permissões em ~/.hermes (700)

━━━ Config ━━━

PASS config.json válido (chmod 600)

PASS ANTHROPIC_API_KEY no env

WARN Telemetria opt-in não definida

━━━ Rede ━━━

PASS api.anthropic.com alcançável

PASS Latência mediana: 187ms

━━━ Skills ━━━

PASS research v1.2.0

PASS code v1.4.1

PASS review v0.9.3

11/12 PASS · 1 WARN · 0 FAIL

🔁 Fluxo de troubleshooting

1.Rode hermes doctor — sempre primeiro. Identifica 90% dos problemas comuns.

2.Aplique hermes doctor --fix — auto-corrige permissões erradas, diretórios faltantes e configs corrompidas.

3.Inspecione ~/.hermes/logs/ — logs estruturados das últimas 100 execuções.

4.Se persistir, hermes init --reset — recria a estrutura preservando memory/.

📋 Checklist pós-instalação

☐node --version retorna v20.x ou superior
☐hermes --version imprime versão sem erro
☐~/.hermes/ existe com permissão 700
☐$ANTHROPIC_API_KEY está exportada e válida
☐hermes ping conecta em menos de 1s
☐hermes run "ping" retorna sem erro
☐hermes doctor mostra 0 FAIL

🔑 Conceitos-chave

12 checks categorizados

Sistema, Config, Rede e Skills — cada um com PASS/WARN/FAIL

--fix idempotente

Auto-corrige permissões e diretórios sem destruir dados existentes

Doctor antes de tudo

Toda dúvida começa rodando hermes doctor — economiza horas

Reset preserva memory

--reset recria estrutura mas preserva memory/ e jobs/

✅ Resumo do Módulo

✓

Pré-requisitos checados — Node 20+, npm sem sudo, API key Anthropic válida e shell POSIX

✓

Instalação em duas etapas — npm install -g hermes-agent seguido de hermes init idempotente

✓

Configuração em camadas — env vars para segredos, ~/.hermes/config.json para usuário, .hermes.json por projeto

✓

Smoke test mínimo — hermes ping + hermes status + um job trivial cobrem o pipeline

✓

Pantheon como painel — UI read-only em localhost:7777 para auditar jobs, skills, memory e logs

✓

hermes doctor antes de avançar — 0 FAIL nos 12 checks é o portão de qualidade pré-trabalho real

Próximo Módulo:

2.2 — Configurando OpenRouter como fallback de modelo

← Voltar para Trilha 2 Próximo Módulo →