⚙️ Instalação e Setup

Instalação nativa em distros Debian/Ubuntu/Fedora usando Python 3.11+ via apt/dnf e pip dentro de virtualenv.

Linux é o ambiente recomendado para o Hermes: melhor performance, suporte completo a MCP e zero atrito com bots.

python3-venv, pip install hermes-agent, isolamento de dependências, PATH e shells (bash/zsh).

Instalação no macOS via Homebrew + pyenv, compatível com M1/M2/M3 (ARM64) e Intel.

macOS é o segundo SO mais usado por devs do Hermes; Apple Silicon exige cuidado com wheels nativas.

brew install python@3.12, arch -arm64, Xcode CLT, sandbox do macOS.

Subsystem Linux dentro do Windows 11 — roda Ubuntu real com kernel próprio e systemd opcional.

Combina UX do Windows com toolchain Linux: melhor caminho pra devs Windows usarem Hermes sem dor.

wsl --install, Ubuntu 22.04, integração com VSCode, port forwarding para bots.

Emulador de terminal Android que roda Hermes nativamente — sem root, com pacotes próprios.

Permite levar o agente no celular: responde Telegram, faz scrapes, monitora APIs offline-first.

pkg install python clang, wake-lock, storage permission, limitações ARM/ndk.

Instalação direta no Windows usando Python.org + venv + PowerShell, sem subsystem Linux.

Necessário quando WSL não está disponível (Win10 sem update, políticas de TI corporativa).

py -3.12 -m venv, ExecutionPolicy, Activate.ps1, paths com espaço, encoding UTF-8.

Comando que pergunta provider, modelo padrão, canais e cria ~/.hermes/config.toml automaticamente.

Substitui edição manual de YAML/TOML; valida tokens em tempo real e evita 90% dos erros de primeira instalação.

interactive prompts, hermes doctor, secrets em keyring do SO, --skip-validation, --reset.

Gateway unificado pra 200+ modelos (Claude, GPT, Hermes-3) com 1 só chave sk-or-....

Provider padrão do Hermes — trocar modelo vira config, não código. Free tier generoso.

openrouter.ai/keys, OPENROUTER_API_KEY, model routing, fallback chains, cost limits.

Bot criado via @BotFather com token 123:ABC... que vira canal Hermes em segundos.

Canal mais leve e ubíquo — funciona em qualquer celular sem app extra.

/newbot, TELEGRAM_BOT_TOKEN, long polling vs webhook, chat_id, allowed_users.

Application no Developer Portal do Discord com bot user, token e intents declaradas.

Comunidade Nous mora no Discord; ideal pra colaboração em times e channels temáticos.

application.id, bot scopes, MESSAGE CONTENT intent, OAuth URL, guild permissions.

Slack app criada em api.slack.com com bot token xoxb-... e socket mode opcional.

Padrão em empresas — coloca o Hermes onde o time já trabalha, sem migrar ninguém.

Bot Token Scopes, app_mentions:read, chat:write, Socket Mode, signing secret.

Primeiro hermes chat via terminal (TUI) e via bot conectado — fechamento do círculo.

Valida que toda a stack está funcionando: provider, modelo, contexto e canal de saída.

hermes chat, /tools, /history, streaming responses, exit codes, logs em ~/.hermes/.

Comando que lê ~/.openclaw/ e converte configs, prompts e tools para o formato Hermes.

Devs vindos do OpenClaw mantêm seus customizações sem refazer manualmente.

--dry-run, --backup, mapeamento de tools MCP, profile merge, rollback automático.

Tenant = usuário lógico com ID, namespace de memória, profile e quota próprios.

É a base de tudo: roteamento, secrets, skills e logs derivam do tenant resolvido.

tenant_resolver, strict_users, default_tenant, namespaces, audit leak-check.

Três estratégias: 1 chave master+quota, sub-keys OpenRouter, ou BYOK (cada user traz a sua).

Escolha errada = fatura explode no fim do mês ou um user trava acesso dos outros.

hermes user secrets set, monthly_usd, sub-key limits, rotação de chaves.

Per-user DB (1 SQLite por tenant) vs namespaced (WHERE tenant_id em DB único).

Bug #1 em multi-tenant é vazamento de memória semântica entre usuários.

per_user_index, backup seletivo, encryption=age, audit leak-check.

Skills em skills/shared/ (todos) ou skills/<user>/ (só dono).

Promover skill com credencial pra shared vaza segredo. Dividir certo evita N cópias.

hermes skill install --scope, skill promote, skill audit, sandboxing.

3 níveis: tokens/dia, custo/mês, rate/min — definidos por tenant.

Um filho perguntando "explica toda física quântica" zera o budget familiar sem quota.

monthly_usd, daily_tokens, rate_per_min, warn_at_pct, hard_stop_at_pct.

Mapeamento ID externo (Telegram chat_id, Discord user_id, Slack user_id) → tenant interno.

Errar mapping = mensagem da Alice cai no contexto do Bob. Grupo TG é caso especial.

exact_match, unknown_action=deny, group_strategy, hermes route test/trace.

Erros #1-4: Python <3.11, externally-managed, venv não ativado, conflito tiktoken/numpy.

Bloqueiam instalação inicial em distros recentes (Debian 12, Ubuntu 24.04).

deadsnakes/ppa, pipx, PEP 668, force-reinstall, source venv/bin/activate.

Erros #5-7: ConnectTimeout, gaierror DNS, CERTIFICATE_VERIFY_FAILED.

Aparecem em VPN corporativa, WSL, Termux, proxy MITM (Zscaler).

HTTPS_PROXY, REQUESTS_CA_BUNDLE, /etc/resolv.conf, certifi --upgrade.

Erros #8-11: OpenRouter 401, Telegram InvalidToken, Discord PrivilegedIntents, Slack invalid_auth.

Copy/paste com espaço, scope errado e intent não habilitada são 40% dos tickets.

curl /getMe, MESSAGE CONTENT INTENT, xoxb vs xapp, Reinstall to Workspace.

Erros #12-14: Permission denied (sudo contaminou), No space left, Windows com espaço no nome.

Disco enche silenciosamente; sudo uma vez quebra tudo daquele user.

chown -R, maintenance prune-logs, HERMES_HOME, du -sh, vacuum.

Erros #15-17: model 404, rate limit em :free, context length exceeded.

Modelos do OpenRouter mudam de nome; free tier tem 20 req/min e 200/dia.

hermes models list, fallback chain, memory.auto_compress, /clear.

Erros #18-20: porta 7777 ocupada, PID file stale, exit 137 (OOM kill silencioso).

Quando rodando como serviço (systemd/Docker), logs do app NÃO capturam crash por OOM.

ss -tlnp, lsof -ti, journalctl, dmesg, MemoryMax, doctor --deep --export.