🛠️ Manutenção e Operação

Comando que percorre Python, dependências, API keys, permissões de pastas, banco SQLite e conectividade com provedores. Imprime ✓/✗ por checagem.

90% dos bugs em produção viram triviais quando você roda doctor antes de pedir ajuda. É a primeira coisa a fazer quando algo quebra.

Checks bloqueantes vs avisos, exit code (0=ok, 1=warn, 2=fail), flag --verbose, integração com CI.

Atualizador interno que respeita canais (stable/beta/nightly), faz pin de versão e migra schema do banco quando necessário.

Update mal feito apaga skills, corrompe memória ou quebra integrações. Saber escolher canal e ler changelog evita dor.

Canais (stable, beta, nightly), --dry-run, snapshot antes do upgrade, breaking changes no CHANGELOG.

Hermes mantém logs estruturados (JSONL) em ~/.hermes/logs/ (Linux/Mac) ou %APPDATA%\hermes\logs\ (Windows). Rotação diária, retenção 14 dias.

Logs são o único registro do que o agente fez. Sem ler logs você fica chutando bug. Com logs, debug é metódico.

Níveis (DEBUG/INFO/WARN/ERROR), filtrar com jq, correlation_id por sessão, log shipping (Loki, Datadog).

Variável HERMES_DEBUG=1 ativa logs verbose, dump de prompts, traces de chamadas a tools e exibição do raciocínio (chain-of-thought) quando disponível.

Sem debug você vê o efeito, não a causa. Com debug você vê exatamente qual prompt foi enviado, qual tool falhou e por quê.

Variáveis HERMES_TRACE, HERMES_PROFILE, sanitização de tokens em dumps, debug seletivo por módulo.

Tuning de latência (provedor, modelo, streaming), gestão de janela de contexto, cache de prompt e de embeddings.

Sem performance, agente fica caro e lento. Cache certo derruba custo em 60-80%.

Prompt caching, p50/p95, time-to-first-token, batching, RAG eficiente.

Mecanismo para voltar à versão anterior preservando memória e skills. Cada update grava snapshot em ~/.hermes/snapshots/.

Update ruim acontece. Saber reverter em 30 segundos é a diferença entre incidente e catástrofe.

hermes rollback --to LAST, snapshot ID, migração reversa de schema, retenção de snapshots.

Empacotar ~/.hermes/ (memória SQLite + skills + configs) em um tarball cifrado.

Perder memória é perder o agente que você treinou por meses. Backup vira investimento.

VACUUM INTO no SQLite (backup hot), cifragem com age, frequência (diário) e teste de restore.

Procedimento para subir Hermes do zero em outra máquina/SO usando o backup.

Backup que não foi testado não existe. Restore é o teste real.

Paths diferentes por SO, recompilação de venv, migração de schema, sanity check com hermes doctor.

Tirar keys de .env e mover para password-store (pass), 1Password CLI, AWS Secrets Manager ou Vault.

Key vazada em repo público é incidente comum e caro. Rotação automática protege.

Princípio do menor privilégio, rotação ≤90 dias, escopo por projeto, scan de segredos (gitleaks).

Rodar Hermes dentro de container Docker/Podman ou sandbox com firejail/bubblewrap para limitar o que tools podem ler/escrever.

Agente com shell e sem sandbox é arma carregada. Isolamento contém estrago de prompt injection.

Volumes read-only, seccomp, network namespaces, allowlist de domínios.

Métricas (Prometheus/OpenTelemetry), alertas (PagerDuty, ntfy) e dashboards de custo do provedor LLM.

Sem monitor, surpresa de fatura de US$ 800 vira regra. Com monitor, vira anomalia detectada.

SLI/SLO, budget de tokens, taxa de erro por tool, alertas por threshold de custo diário.

Playbook para incidentes: key vazada, fatura disparada, loop infinito, memória corrompida.

Em incidente, decisão sob pressão tende ao erro. Playbook escrito vira piloto automático.

Contenção, erradicação, recuperação, post-mortem blame-free, runbooks versionados.

Painel oficial em openrouter.ai/activity com custo, tokens, cache hit e modelo por requisição.

Sem dashboard você otimiza no escuro. É a fonte da verdade para decidir o que mexer.

Activity, Credits, Keys com credit limit, API /credits e /generations.

Três camadas: aviso suave (70%), aviso duro (90%) e parada total (100%) + daily_usd_limit local no Hermes.

Sem alerta, a primeira notícia é a fatura. Camadas dão tempo de investigar antes do estouro.

Auto-recarga desligada, runaway costs por loop infinito, max_tool_iterations.

Routing por tipo de tarefa em config.yaml: Haiku 4.5 para classify, Sonnet 4.6 default, Opus 4.7 só para raciocínio pesado.

Opus é 15× mais caro que Haiku. Usar Opus para classify queima dinheiro sem ganho.

Preços OpenRouter por 1M tokens, model_routing.tasks, eval antes de trocar.

Mecanismo Anthropic que dá ~90% de desconto em tokens de input que se repetem entre chamadas (system, tools, RAG fixo).

É a otimização mais lucrativa por linha de config. Corta facilmente 40-50% do gasto sozinha.

Prefixo estável, TTL de 5 min, mínimo 1024 tokens, cache_discount nas métricas.

Cadeia primary → fallbacks no model_routing: troca para provedor barato em 429/5xx/timeout.

Mantém o agente vivo em outage e evita fatura disparada por re-tentativa em loop.

Trigger por rate_limit/5xx, max_retries, log de demotion, 1-shot > few-shot.

Auditoria passo-a-passo de instalação típica: routing + caching + max_iterations + 1-shot, com números reais.

Mostra a ordem de aplicação e o impacto de cada etapa. Replicável em qualquer setup.

Baseline, -50% routing, -40% adicional caching, -22% adicional loops, total -76,7%.

Três canais de release: stable (mensal), beta (quinzenal), nightly (HEAD diário). Cada um com risco e cadência próprios.

Prod em nightly é convite à quebra; dev em stable atrasa em features. Escolha por máquina.

Pin exato (==X.Y.Z), --pre, instalação via git, hermes version --verbose.

Hábito de ler o CHANGELOG inteiro entre versão atual e alvo antes de instalar.

90% dos incidentes pós-upgrade são causados por não ter lido. 5 min poupam horas.

BREAKING, Removed, Migration, Deprecated, Security. Major sempre quebra.

Segundo Hermes em HERMES_HOME separado, com cópia de memória e key dev, para validar antes de promover.

Staging é barato (sem máquina extra) e captura 80% dos bugs antes de tocar produção.

pipx install --suffix, VACUUM INTO, smoke tests reais, 24-48h em paralelo.

Bloco de tempo planejado para o upgrade, com pessoas disponíveis e baixa demanda.

Hora ruim transforma incidente recuperável em catástrofe (sexta à noite, véspera de feriado).

Terça/quarta manhã, evitar sexta, considerar fuso de usuários, avisar antes.

Mecanismo do Hermes para voltar à versão anterior em < 60 segundos, com snapshot por update.

Rollback bom é rollback ensaiado. Descobrir como reverter durante incidente é tarde.

hermes rollback --to LAST, retenção de snapshots, sinais que pedem rollback.

Quatro blocos de 1-3h por ano com ritmo previsível: audit completo, minor update, audit de custo+security, major window.

Manutenção saudável é ritmo, não heroísmo. Sem calendário, vira congelamento na v0.8.

Cadência típica Nous Research (patch 2sem, minor 2 meses, major anual), pip-audit, playbook 10 passos.