Instalação

Coloque o Hermes Agent para rodar em menos de dois minutos.

Suporte a plataformas

Para a matriz completa — quais sistemas operacionais, quais métodos de distribuição e quais recursos dependem da plataforma — veja Suporte a Plataformas.

Instalação rápida

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

Para instalar de uma vez os aplicativos de linha de comando e o desktop, baixe o instalador do Hermes Desktop no site oficial e execute.

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)

Se depois quiser instalar e abrir o Hermes Desktop, basta rodar:

hermes desktop

O que o instalador faz

O instalador cuida de tudo sozinho — todas as dependências (Python, Node.js, ripgrep, ffmpeg), o clone do repositório, o ambiente virtual, o comando global hermes e a configuração do provedor de LLM. No fim, é só conversar.

Onde os arquivos ficam

Depende de você instalar como usuário comum ou como root:

Instalação	Código fica em	Binário hermes	Diretório de dados
Por usuário (instalador git)	~/.hermes/hermes-agent/	~/.local/bin/hermes (symlink)	~/.hermes/
Como root (sudo curl … | sudo bash)	/usr/local/lib/hermes-agent/	/usr/local/bin/hermes	/root/.hermes/ (ou $HERMES_HOME)

O layout FHS do modo root (/usr/local/lib/…, /usr/local/bin/hermes) é o mesmo lugar onde outras ferramentas de desenvolvimento se instalam no Linux para o sistema inteiro. Serve para máquinas compartilhadas, em que uma instalação atende todos os usuários. A configuração de cada pessoa (autenticação, skills, sessões) continua em ~/.hermes/ ou no HERMES_HOME que ela definir.

Depois de instalar

Recarregue o shell e comece a conversar:

source ~/.bashrc   # ou: source ~/.zshrc
hermes             # começa a conversa

Para mexer em configurações específicas depois, use os comandos dedicados:

hermes model          # escolhe o provedor de LLM e o modelo
hermes tools          # define quais ferramentas ficam ativas
hermes gateway setup  # configura as plataformas de mensagem
hermes config set     # define um valor de configuração
hermes config get     # consulta um valor de configuração
hermes setup          # ou roda o assistente completo, que configura tudo de uma vez

Caminho mais curto: Nous Portal

Uma assinatura cobre 300+ modelos mais o Tool Gateway (busca na web, geração de imagem, voz, navegador na nuvem). Dispensa ficar caçando chave de API para cada ferramenta:

hermes setup --portal

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

Já usa o Hermes em outra máquina?

Não precisa refazer a configuração do zero. Restaure um backup completo com hermes import, ou traga só um agente com hermes profile import. Atenção: a exportação de perfil não inclui credenciais, de propósito — então ela sozinha não é um backup completo. Veja hermes backup vs hermes profile export para saber qual usar.

---

Pré-requisitos

Fora do Windows, o único pré-requisito é o Git. No Linux, garanta também curl e xz-utils — o instalador baixa o Node.js num arquivo .tar.xz. O aplicativo desktop exige ainda o g++ (ou build-essential no Debian/Ubuntu) para compilar módulos nativos. O resto o instalador resolve:

• uv (gerenciador de pacotes Python rápido)
• Python 3.11 (via uv, sem precisar de sudo)
• Node.js v22 (para automação de navegador e a ponte com o WhatsApp)
• ripgrep (busca rápida em arquivos)
• ffmpeg (conversão de áudio para a síntese de voz)

informação

Você não precisa instalar Python, Node.js, ripgrep nem ffmpeg na mão. O instalador detecta o que falta e instala. Só confira se o git está disponível (git --version). No Linux, garanta curl e xz-utils (sudo apt install curl xz-utils no Debian/Ubuntu). Para o aplicativo desktop, instale também o build-essential (sudo apt install build-essential).

Quem usa Nix

O Nix deixou de ser um caminho de instalação oficialmente suportado — o suporte agora é só por esforço da comunidade. Se você já usa Nix (no NixOS, macOS ou Linux), existe um caminho próprio, com flake, módulo declarativo para NixOS e modo container opcional. Veja o guia Nix e NixOS.

---

Instalação manual, para desenvolvimento

Se você quer clonar o repositório e instalar a partir do código-fonte — para contribuir, rodar um branch específico ou controlar o ambiente virtual por completo — veja a seção Development Setup no guia de contribuição.

---

Instalação sem sudo, ou como usuário de serviço

Rodar o Hermes como usuário sem privilégios (uma conta hermes de serviço no systemd, por exemplo, ou qualquer usuário sem sudo) é suportado. A única etapa da instalação que realmente precisa de root é o --with-deps do Playwright, que instala via apt as bibliotecas compartilhadas do Chromium (libnss3, libxkbcommon e afins). O instalador detecta se há sudo e se adapta quando não há: instala o binário do Chromium no cache local do próprio usuário e imprime o comando exato que um administrador precisa rodar à parte.

Divisão recomendada (Debian/Ubuntu):

1. Uma vez só, como administrador com sudo, instale as bibliotecas de sistema do Chromium:

   sudo npx playwright install-deps chromium

   (Pode rodar de qualquer diretório — o npx baixa o Playwright na hora.)

2. Como o usuário de serviço, rode o instalador normal. Ele vai perceber a falta de sudo, pular o --with-deps e instalar o Chromium no cache local do Playwright desse usuário:

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

   Se quiser pular o Playwright por completo — por exemplo, num servidor sem interface gráfica em que automação de navegador não faz falta — passe --skip-browser:

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

   O instalador também já deixa o cua-driver pronto, para o conjunto de ferramentas de Computer Use funcionar assim que você ligar. Passe --skip-computer-use para não instalar agora (ele será instalado sob demanda quando a ferramenta for ativada).

3. Deixe o hermes acessível nos shells do usuário de serviço. O instalador grava o lançador em ~/.local/bin/hermes. Contas de serviço costumam ter um PATH mínimo, sem ~/.local/bin. Ou você acrescenta ao ambiente do usuário, ou cria um symlink num local do sistema:

   # Opção A — acrescentar ao perfil do usuário de serviço
   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   
   # Opção B — symlink para o sistema inteiro (rodar como administrador)
   sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes

4. Confira: o hermes doctor deve rodar limpo. Se aparecer ModuleNotFoundError: No module named 'dotenv', você está chamando o arquivo hermes do código-fonte (~/.hermes/hermes-agent/hermes) com o Python do sistema, em vez do lançador do ambiente virtual (~/.hermes/hermes-agent/venv/bin/hermes) — corrija o passo 3.

5. Vai rodar o gateway de mensagens nessa conta? Um serviço de usuário para no logout e não sobe no boot enquanto você não habilitar o lingering para o usuário de serviço:

   sudo loginctl enable-linger <usuario-de-servico>

   A configuração do serviço em si está em Gateway de Mensagens.

O mesmo padrão vale no Arch (o instalador usa pacman com a mesma lógica de detecção de sudo), no Fedora/RHEL e no openSUSE — essas distribuições não suportam --with-deps de jeito nenhum, então um administrador sempre instala as bibliotecas de sistema à parte. Os comandos dnf e zypper correspondentes são impressos pelo instalador.

---

Resolução de problemas

Problema	Solução
hermes: command not found	Recarregue o shell (source ~/.bashrc) ou confira o PATH
API key not set	Rode hermes model para configurar o provedor, ou hermes config set OPENROUTER_API_KEY sua_chave
Configuração sumiu depois de atualizar	Rode hermes config check e depois hermes config migrate

Para um diagnóstico mais completo, rode hermes doctor — ele diz exatamente o que está faltando e como resolver.

Detecção automática do método de instalação

O Hermes descobre sozinho se foi instalado pelo instalador git, por Docker ou por NixOS, e o hermes update imprime o comando de atualização correspondente. Não há variável de ambiente para configurar isso — a detecção olha o layout da instalação (o diretório ~/.hermes/hermes-agent/, o carimbo da imagem Docker ou o caminho na Nix store). O hermes doctor também mostra o método detectado no resumo do ambiente.