Início Rápido

Este guia leva você do zero a uma instalação do Hermes que aguenta uso de verdade. Instalar, escolher um provedor, confirmar que a conversa funciona e saber exatamente o que fazer quando algo quebrar.

Prefere assistir?

O Onchain AI Garage montou uma masterclass cobrindo instalação, configuração e comandos básicos — boa companhia para esta página se você prefere acompanhar em vídeo. O vídeo está em inglês. Tem mais na playlist Hermes Agent Tutorials & Use Cases.

Para quem é

• Nunca usou e quer o caminho mais curto até algo funcionando
• Está trocando de provedor e não quer perder tempo com erro de configuração
• Está montando o Hermes para uma equipe, um bot ou algo que fica ligado o tempo todo
• Cansou do "instalou, mas continua não fazendo nada"

O caminho mais rápido

Escolha a linha que combina com seu objetivo:

Objetivo	Faça isto primeiro	Depois
Só quero o Hermes rodando na minha máquina	hermes setup	Puxe uma conversa de verdade e confirme que ele responde
Já sei qual provedor quero	hermes model	Salve a configuração e comece a conversar
Quero um bot ou algo sempre ligado	hermes gateway setup, depois que a CLI funcionar	Conecte Telegram, Discord, Slack ou outra plataforma
Quero um modelo local ou auto-hospedado	hermes model → endpoint personalizado	Confira endpoint, nome do modelo e tamanho de contexto
Quero reserva entre vários provedores	hermes model primeiro	Acrescente roteamento e reserva só depois que a conversa básica funcionar

Regra prática: se o Hermes não consegue completar uma conversa normal, não acrescente mais nada ainda. Primeiro uma conversa limpa; depois gateway, cron, skills, voz ou roteamento.

---

1. Instalar o Hermes Agent

Com o instalador do Hermes Desktop, no macOS ou Windows (recomendado)

Baixe o instalador do Hermes Desktop no site oficial e execute — ele instala a linha de comando e o aplicativo desktop.

Sem o Hermes Desktop

Para instalar só a linha de comando:

Linux / macOS / WSL2 / Android (Termux)

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (nativo)

No PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Android / Termux

Se você está instalando num celular, veja o guia do Termux para o caminho manual testado, os extras suportados e as limitações atuais no Android.

Quando terminar, recarregue o shell:

source ~/.bashrc   # ou source ~/.zshrc

Opções detalhadas, pré-requisitos e resolução de problemas estão no guia de Instalação.

2. Escolher um provedor

O passo mais importante da configuração. Use hermes model para decidir de forma interativa:

hermes model

Caminho mais fácil: Nous Portal

Uma assinatura cobre 300+ modelos mais o Tool Gateway (busca na web, geração de imagem, voz, navegador na nuvem). Numa instalação nova:

hermes setup --portal

Esse comando faz o login, define a Nous como provedor e liga o Tool Gateway, tudo junto.

Modos de configuração

Numa instalação nova, o hermes setup oferece três modos:

• Quick Setup (Nous Portal) — login OAuth gratuito, sem chave de API; configura um modelo mais as ferramentas do Tool Gateway. É o caminho rápido recomendado.
• Full Setup — você passa por cada provedor, ferramenta e opção, usando suas próprias chaves.
• Blank Slate — tudo começa desligado, exceto o mínimo para rodar um agente: provedor e modelo, o conjunto de operações com arquivos e o conjunto do terminal. Sem web, navegador, execução de código, visão, memória, delegação, cron, skills, plugins ou servidores MCP — e com compressão, checkpoints, roteamento inteligente e captura de memória todos desativados. Depois desse mínimo, você escolhe entre dois caminhos: terminar com tudo desligado (agente mínimo, e acabou) ou passar por todas as configurações (ligando ferramentas, skills, plugins, MCP e mensagens). Escolha este modo quando quiser um agente enxuto, sob controle total, ligando só exatamente o que precisa.

O Blank Slate grava uma lista explícita em platform_toolsets.cli mais o agent.disabled_toolsets, então nada que você não escolheu chega a carregar — nem depois de um hermes update. Para religar algo depois, use hermes tools; para trazer skills, hermes skills opt-in --sync; para ajustar o resto, hermes setup agent.

Bons padrões:

Provedor	O que é	Como configurar
Nous Portal	Por assinatura, sem configuração	Login OAuth por hermes model
OpenAI Codex	Assinatura do ChatGPT ou Codex, usa os modelos Codex	Autenticação por código de dispositivo em hermes model → ChatGPT or Codex Subscription
Anthropic	Modelos Claude direto — plano Max mais créditos extras (OAuth), ou chave de API para pagar por token	hermes model → login OAuth (exige Max mais créditos) ou uma chave de API da Anthropic
OpenRouter	Roteamento entre muitos provedores e modelos	Informe sua chave de API
Fireworks AI	API de modelos compatível com OpenAI	Defina FIREWORKS_API_KEY
Z.AI	Modelos GLM / Zhipu	Defina GLM_API_KEY / ZAI_API_KEY (também aceita Z_AI_API_KEY)
Kimi / Moonshot	Modelos de código e conversa da Moonshot	Defina KIMI_API_KEY (ou o específico KIMI_CODING_API_KEY)
Kimi / Moonshot China	Endpoint da Moonshot na região da China	Defina KIMI_CN_API_KEY
Arcee AI	Modelos Trinity	Defina ARCEEAI_API_KEY
GMI Cloud	API direta, vários modelos	Defina GMI_API_KEY
Actual Computer	Seu próprio hardware como cluster privado de inferência — relay hospedado ou daemon local	Defina ACTUAL_API_KEY (relay) ou ACTUAL_BASE_URL=http://127.0.0.1:8080 (local, sem chave)
MiniMax (OAuth)	Modelo de fronteira da MiniMax por OAuth no navegador, sem chave (o nome do modelo em hermes_cli/models.py pode mudar entre versões)	hermes model → MiniMax (OAuth)
MiniMax	Endpoint internacional da MiniMax	Defina MINIMAX_API_KEY
MiniMax China	Endpoint da MiniMax na região da China	Defina MINIMAX_CN_API_KEY
Alibaba Cloud	Modelos Qwen via DashScope	Defina DASHSCOPE_API_KEY (o Qwen Coding Plan também aceita ALIBABA_CODING_PLAN_API_KEY)
Hugging Face	20+ modelos abertos por roteador unificado (Qwen, DeepSeek, Kimi etc.)	Defina HF_TOKEN
AWS Bedrock	Claude, Nova, Llama e DeepSeek pela Converse API nativa	Role do IAM ou aws configure (guia)
Azure Foundry	Modelos hospedados no Azure AI Foundry	Defina AZURE_FOUNDRY_API_KEY e AZURE_FOUNDRY_BASE_URL
Google AI Studio	Modelos Gemini por API direta	Defina GOOGLE_API_KEY / GEMINI_API_KEY
xAI	Modelos Grok por API direta	Defina XAI_API_KEY
xAI Grok OAuth	Assinatura SuperGrok / Premium+, sem chave de API	hermes model → xAI Grok OAuth
NovitaAI	Gateway de API com vários modelos	Defina NOVITA_API_KEY
StepFun	Modelos Step Plan	Defina STEPFUN_API_KEY
Xiaomi MiMo	Modelos hospedados pela Xiaomi	Defina XIAOMI_API_KEY
Tencent TokenHub	Modelos hospedados pela Tencent	Defina TOKENHUB_API_KEY
Ollama Cloud	Modelos Ollama gerenciados	Defina OLLAMA_API_KEY
LM Studio	Aplicativo local que expõe uma API compatível com OpenAI	Defina LM_API_KEY (e LM_BASE_URL, se não for o padrão)
Qwen OAuth	OAuth do Qwen Portal pelo navegador, sem chave de API	hermes model → Qwen OAuth
Kilo Code	Modelos hospedados pela KiloCode	Defina KILOCODE_API_KEY
OpenCode Zen	Acesso pré-pago a modelos selecionados	Defina OPENCODE_ZEN_API_KEY
OpenCode Go	Assinatura de US$ 10/mês para modelos abertos	Defina OPENCODE_GO_API_KEY
DeepSeek	Acesso direto à API da DeepSeek	Defina DEEPSEEK_API_KEY
NVIDIA NIM	Modelos Nemotron via build.nvidia.com ou NIM local	Defina NVIDIA_API_KEY (opcional: NVIDIA_BASE_URL)
GitHub Copilot	Assinatura do GitHub Copilot (GPT-5.x, Claude, Gemini etc.)	OAuth por hermes model, ou COPILOT_GITHUB_TOKEN / GH_TOKEN
GitHub Copilot ACP	Backend de agente ACP do Copilot (roda a CLI copilot local)	hermes model (exige a CLI copilot e copilot login)
Vercel AI Gateway	Roteamento pelo Vercel AI Gateway	Defina AI_GATEWAY_API_KEY
Endpoint personalizado	VLLM, SGLang, Ollama ou qualquer API compatível com OpenAI	Defina a URL base e a chave de API

Para quem está começando: escolha um provedor e aceite os padrões, a não ser que você saiba por que está mudando. O catálogo completo, com variáveis de ambiente e passos de configuração, está na página Providers.

Contexto mínimo: 64 mil tokens

O Hermes Agent exige um modelo com pelo menos 64.000 tokens de contexto. Janelas menores não sustentam memória de trabalho suficiente para fluxos com várias chamadas de ferramenta, e são recusadas na inicialização. A maioria dos modelos hospedados (Claude, GPT, Gemini, Qwen, DeepSeek) passa disso com folga. Se você roda um modelo local, configure o contexto para no mínimo 64K (por exemplo --ctx-size 65536 no llama.cpp ou -c 65536 no Ollama).

dica

Dá para trocar de provedor a qualquer momento com hermes model — não há amarra. A lista completa está em AI Providers.

Onde as configurações ficam

O Hermes separa segredo de configuração comum:

• Segredos e tokens → ~/.hermes/.env
• Configurações não sensíveis → ~/.hermes/config.yaml

O jeito mais seguro de definir valores é pela CLI:

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...

Cada valor vai para o arquivo certo automaticamente.

3. Sua primeira conversa

hermes            # CLI clássica
hermes --tui      # TUI moderna (recomendada)

Aparece um banner de boas-vindas com seu modelo, as ferramentas disponíveis e as skills. Use um pedido específico e fácil de verificar:

Escolha sua interface

O Hermes vem com duas interfaces de terminal: a CLI clássica, em prompt_toolkit, e uma TUI mais nova, com sobreposições modais, seleção pelo mouse e entrada que não trava. As duas compartilham sessões, comandos de barra e configuração — experimente hermes e hermes --tui.

Resuma este repositório em 5 tópicos e diga qual é o ponto de entrada principal.

Olhe meu diretório atual e diga qual arquivo parece ser o principal do projeto.

Me ajude a montar um fluxo limpo de pull request no GitHub para este código.

Como saber que deu certo:

• O banner mostra o modelo e o provedor que você escolheu
• O Hermes responde sem erro
• Ele consegue usar uma ferramenta quando precisa (terminal, leitura de arquivo, busca na web)
• A conversa segue normalmente por mais de um turno

Se isso funciona, a parte difícil já passou.

4. Confirmar que as sessões funcionam

Antes de seguir, garanta que dá para retomar:

hermes --continue    # retoma a sessão mais recente
hermes -c            # forma curta

Isso deve trazer você de volta à conversa que acabou de ter. Se não trouxer, veja se você está no mesmo perfil e se a sessão chegou a ser salva. Isso importa mais adiante, quando você estiver lidando com várias configurações ou máquinas.

5. Experimentar os recursos principais

Usar o terminal

❯ Qual é meu uso de disco? Mostre os 5 diretórios maiores.

O agente roda os comandos por você e mostra o resultado.

Comandos de barra

Digite / para ver a lista de comandos com autocompletar:

Comando	O que faz
/help	Mostra todos os comandos
/tools	Lista as ferramentas disponíveis
/model	Troca de modelo de forma interativa
/personality pirate	Experimenta uma personalidade diferente
/save	Salva a conversa

Entrada em várias linhas

Pressione Alt+Enter, Ctrl+J ou Shift+Enter para pular linha. O Shift+Enter depende de um terminal que envie a sequência distinta (Kitty, foot, WezTerm e Ghostty já fazem isso; iTerm2, Alacritty e o terminal do VS Code, depois de habilitar o protocolo de teclado do Kitty). Alt+Enter e Ctrl+J funcionam em qualquer terminal.

Interromper o agente

Se o agente está demorando demais, digite uma mensagem nova e pressione Enter — isso interrompe a tarefa atual e ele passa a seguir a nova instrução. Ctrl+C também funciona.

6. Acrescentar a próxima camada

Só depois que a conversa básica funciona. Escolha o que você precisa:

Bot ou assistente compartilhado

hermes gateway setup    # configuração interativa das plataformas

Conecte Telegram, Discord, Slack, WhatsApp, Signal, e-mail, Home Assistant ou Microsoft Teams.

Automação e ferramentas

• hermes tools — ajusta o acesso às ferramentas por plataforma
• hermes skills — navega e instala fluxos reaproveitáveis
• Cron — só depois que seu bot ou sua CLI estiverem estáveis

Terminal em sandbox

Por segurança, rode o agente num container Docker ou num servidor remoto:

hermes config set terminal.backend docker    # isolamento por Docker
hermes config set terminal.backend ssh       # servidor remoto

Em sandboxes Docker, dá para ligar também o proxy de saída com injeção de credenciais, para que o sandbox nunca veja suas chaves de API de verdade — só tokens opacos, que só funcionam por trás de um daemon local que intercepta TLS. Veja Egress proxy. A configuração é hermes egress setup && hermes egress start; o hermes setup terminal também aponta os usuários de Docker para lá. Modal, SSH, Daytona e Singularity ainda não estão ligados a esse proxy.

Modo de voz

# A partir do diretório de instalação do Hermes (o instalador coloca em
# ~/.hermes/hermes-agent no Linux/macOS, ou %LOCALAPPDATA%\hermes\hermes-agent no Windows):
cd ~/.hermes/hermes-agent
uv pip install --python ./venv/bin/python -e ".[voice]"
# Inclui o faster-whisper, para transcrição local gratuita

Depois, na CLI: /voice on. Pressione Ctrl+B para gravar. Veja Modo de voz.

Skills

Skills são documentos de instrução carregados sob demanda, que ensinam o Hermes a fazer uma tarefa específica — publicar no Kubernetes, abrir um pull request no GitHub, fazer fine-tuning de um modelo, procurar GIFs. Cada uma é um arquivo SKILL.md com nome, descrição e um procedimento passo a passo. O agente lê as descrições curtas de graça e só carrega o conteúdo completo quando a tarefa realmente pede — então acrescentar skills não incha toda requisição.

O Hermes já vem com um catálogo de skills instalado em ~/.hermes/skills/. Dá para acrescentar mais pelo Skills Hub, ou escrever as suas.

Navegar e instalar pelo hub:

hermes skills browse                      # lista tudo que existe
hermes skills search kubernetes           # procura por palavra-chave
hermes skills install openai/skills/k8s   # instala uma (faz varredura de segurança antes)

O argumento de instalação é um identificador origem/caminho do hub — openai/skills/k8s significa a skill k8s do catálogo da OpenAI. O hermes skills browse mostra os identificadores exatos.

Usar uma skill — toda skill instalada vira um comando de barra automaticamente:

/k8s publica o manifesto de staging     # roda a skill com um pedido
/k8s                                     # carrega e deixa o Hermes perguntar o que você quer

Funciona na CLI e em qualquer plataforma de mensagem conectada. Você não precisa instalar tudo de antemão — durante a conversa, o agente escolhe sozinho a skill embutida que serve para a tarefa.

Veja Sistema de skills para escrever as suas, usar diretórios externos e ver a lista completa de fontes do hub.

Servidores MCP

# Acrescente ao ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Integração com o editor (ACP)

O suporte a ACP vem junto com os extras [all], então o instalador via curl já traz. Basta rodar:

hermes acp

(Se você instalou sem o [all], rode antes cd ~/.hermes/hermes-agent && uv pip install -e ".[acp]".)

Veja Integração ACP.

---

Falhas mais comuns

Estes são os problemas que mais fazem perder tempo:

Sintoma	Causa provável	Correção
O Hermes abre mas responde vazio ou quebrado	Autenticação do provedor ou escolha de modelo errada	Rode hermes model de novo e confirme provedor, modelo e autenticação
O endpoint personalizado "funciona" mas devolve lixo	URL base errada, nome de modelo errado, ou o endpoint não é de fato compatível com OpenAI	Teste o endpoint num outro cliente antes
O gateway sobe mas ninguém consegue mandar mensagem	Token do bot, lista de permissão ou configuração da plataforma incompleta	Rode hermes gateway setup de novo e confira hermes gateway status
hermes --continue não acha a sessão antiga	Você trocou de perfil, ou a sessão nunca foi salva	Confira hermes sessions list e veja se está no perfil certo
Modelo indisponível ou reserva se comportando de forma estranha	Roteamento ou reserva configurados de forma agressiva demais	Deixe o roteamento desligado até o provedor principal estar estável
hermes doctor aponta problemas de configuração	Valores faltando ou desatualizados	Corrija a configuração e teste uma conversa simples antes de acrescentar recursos

Kit de recuperação

Quando algo parecer errado, siga nesta ordem:

1. hermes doctor
2. hermes model
3. hermes setup
4. hermes sessions list
5. hermes --continue
6. hermes gateway status

Essa sequência tira você do "está estranho" e devolve a um estado conhecido, rápido.

---

Referência rápida

Comando	Descrição
hermes	Começa a conversar
hermes model	Escolhe o provedor de LLM e o modelo
hermes tools	Define quais ferramentas ficam ativas por plataforma
hermes setup	Assistente completo (configura tudo de uma vez)
hermes doctor	Diagnostica problemas
hermes update	Atualiza para a versão mais recente
hermes gateway	Sobe o gateway de mensagens
hermes --continue	Retoma a última sessão

Próximos passos

• Visão geral dos recursos — tudo que o Hermes sabe fazer
• Memória persistente — como ele lembra entre sessões
• Trilha de aprendizado — por onde seguir, conforme seu nível
• Guia da CLI — dominar a interface de terminal
• Configuração — personalizar sua instalação
• Gateway de mensagens — conectar Telegram, Discord, Slack, WhatsApp, Signal, e-mail, Home Assistant, Teams e mais
• Mudar de máquina — o hermes backup leva a instalação inteira (ou só um perfil); sem refazer do zero