⚡ AutomationsAI|Portal de Cursos →

Verificando acesso...

MÓDULO 3.1

💻 Instalação no seu sistema

Linux, macOS, WSL2, Termux, Windows nativo e o wizard hermes setup — escolha seu SO e vá do pip install ao primeiro hermes --version em menos de 10 minutos.

6
Tópicos
~45
Minutos
Básico
Nível
Hands-on
Tipo
1

🐧 Linux — apt, pip, virtualenv

Linux é o ambiente primeira-classe do Hermes Agent. Tudo é testado em Ubuntu 22.04+ e Fedora 39+ antes de cada release. Se você tem dúvida em qual SO instalar — escolha Linux.

📊 Versões mínimas

  • Python: 3.11+ (3.12 recomendado, 3.13 funciona)
  • RAM: 2 GB livres (8 GB confortável)
  • Disco: 500 MB pra core + 1-3 GB pra cache de modelos
  • Kernel: 5.4+ (qualquer LTS recente)

Ubuntu / Debian — passo a passo

# 1. Atualize o sistema e instale Python 3.12 + venv
sudo apt update
sudo apt install -y python3.12 python3.12-venv python3-pip git

# 2. Crie um ambiente isolado pro Hermes
python3.12 -m venv ~/.venvs/hermes
source ~/.venvs/hermes/bin/activate

# 3. Instale o pacote
pip install --upgrade pip
pip install hermes-agent

# 4. Verifique
hermes --version
# → hermes-agent 1.x.x (python 3.12.x on linux)

Fedora / RHEL

sudo dnf install -y python3.12 python3-pip git
python3.12 -m venv ~/.venvs/hermes
source ~/.venvs/hermes/bin/activate
pip install hermes-agent

✓ O que FAZER

  • ✓Usar venv isolado em ~/.venvs/hermes
  • ✓Atualizar pip antes de instalar
  • ✓Adicionar source ~/.venvs/hermes/bin/activate ao .bashrc
  • ✓Considerar pipx install hermes-agent como alternativa zero-config

✗ O que NÃO fazer

  • ✗sudo pip install — quebra dependências do sistema
  • ✗Usar Python 3.8 ou 3.9 — não há suporte (typing moderno)
  • ✗Instalar globalmente fora de venv — conflitos com APT
  • ✗Esquecer de ativar o venv antes de rodar hermes

💡 Dica — pipx

Se você só quer rodar o CLI sem se preocupar com venvs, instale via pipx install hermes-agent. O pipx cria o venv automaticamente e expõe o binário em ~/.local/bin/hermes. Ideal pra estações de trabalho de devs.

2

🍎 macOS — brew, pyenv, Apple Silicon

macOS é o segundo SO mais usado pela comunidade Hermes. Funciona perfeitamente em M1/M2/M3 e Intel — só não use o Python que vem com o sistema (é 3.9 e a Apple pediu pra não usar).

💡 Caminho recomendado: Homebrew

Homebrew gerencia Python, OpenSSL e dependências nativas (libffi, etc) automaticamente. É o padrão de fato em desenvolvimento macOS.

  • •Suporta M1/M2/M3 (arm64) nativamente
  • •Atualiza Python sem mexer no sistema
  • •Funciona com VSCode, PyCharm e iTerm2 sem extra config

Instalação com Homebrew

# 1. Instale Homebrew se ainda não tem
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Instale Python 3.12
brew install python@3.12

# 3. Crie venv e instale
python3.12 -m venv ~/.venvs/hermes
source ~/.venvs/hermes/bin/activate
pip install --upgrade pip
pip install hermes-agent

# 4. Verifique
hermes --version

Alternativa: pyenv (múltiplas versões)

brew install pyenv
pyenv install 3.12.7
pyenv global 3.12.7

# Adicione ao ~/.zshrc:
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc

pip install hermes-agent

⚠️ Atenção — Apple Silicon

Se você herdou um terminal Rosetta (Intel emulado), comandos como arch retornam i386. Verifique com arch antes — deve retornar arm64. Caso contrário, abra um Terminal novo ou force com arch -arm64 brew install python@3.12. Wheels nativas economizam 3-5× em performance.

💡 Dica — Xcode CLT

Algumas dependências do Hermes compilam código C nativo (cryptography, lxml). Se pip install falhar com erro de compilador, rode xcode-select --install uma vez e tente novamente.

3

🪟 WSL2 — Windows com Linux real

WSL2 entrega uma VM Linux de verdade dentro do Windows, com kernel próprio e integração transparente com VSCode, Docker e PowerShell. É o caminho recomendado pra devs Windows.

Habilitar WSL2 + Ubuntu

1

Abra PowerShell como Administrador

Botão direito no menu Iniciar → "Terminal (Admin)"

wsl --install -d Ubuntu-22.04

Isso instala WSL2, kernel Linux e Ubuntu 22.04 de uma vez. Reinicie quando pedir.

2

Crie usuário Linux e atualize

Após reiniciar, o Ubuntu abre e pede usuário/senha

sudo apt update && sudo apt upgrade -y
3

Siga o caminho Linux

Agora é Linux puro — use o procedimento do Tópico 1

sudo apt install python3.12 python3.12-venv -y && pip install hermes-agent
4

Conecte VSCode

Instale a extensão "WSL" do VSCode e abra qualquer pasta com code . dentro do Ubuntu

📊 WSL2 vs Windows nativo

  • I/O em /home/user: ~10× mais rápido que /mnt/c/
  • Compatibilidade MCP: 100% (vs 80% em Windows nativo)
  • Compilação de wheels: não precisa Visual Studio Build Tools
  • Bots long-polling: sem firewall do Windows no caminho
4

📱 Termux — Android no bolso

Termux roda Hermes Agent no celular Android sem root. Útil pra responder Telegram em mobilidade, monitorar APIs ou ter um agente sempre ligado num chip 4G.

⚠️ Instale da F-Droid, não da Play Store

O Termux da Play Store está desatualizado desde 2020 e não recebe mais patches. Baixe sempre de f-droid.org/packages/com.termux — versões atuais com Python 3.12.

Setup completo no Termux

# 1. Atualize pacotes
pkg update && pkg upgrade -y

# 2. Instale Python, clang (pra wheels nativas) e git
pkg install -y python clang git openssl libffi rust

# 3. Permita acesso ao armazenamento (pra logs e configs persistentes)
termux-setup-storage

# 4. Instale Hermes Agent
pip install --upgrade pip
pip install hermes-agent

# 5. Mantenha rodando em background
pkg install -y termux-services
sv-enable hermes  # após hermes setup

💡 Dica — wake-lock

Android mata processos em background pra economizar bateria. Antes de iniciar o Hermes, rode termux-wake-lock. Quando terminar, termux-wake-unlock. Sem isso, seu bot some depois de 10 minutos com a tela apagada.

✓ Cenários ideais

  • ✓Bot Telegram pessoal sempre disponível
  • ✓Lab de desenvolvimento offline
  • ✓Demos rápidas em reunião
  • ✓Edge cases com 3G/4G só

✗ Cenários ruins

  • ✗Produção crítica (Android mata processos)
  • ✗Modelos locais grandes (RAM limitada)
  • ✗Tools MCP que exigem Docker
  • ✗Multi-canal com alta vazão

Referência oficial: hermes-agent.nousresearch.com/docs/getting-started/termux

5

💠 Windows PowerShell — Sem WSL, nativo

Quando WSL não é opção (Windows 10 antigo, política de TI, máquina pessoal sem hyper-v), você pode rodar Hermes nativo no Windows via Python.org + PowerShell.

Passo a passo

# 1. Baixe Python 3.12 de python.org/downloads
#    DURANTE INSTALAÇÃO: marque "Add python.exe to PATH"

# 2. Abra PowerShell (não como admin) e verifique
py -3.12 --version
# → Python 3.12.7

# 3. Permita execução de scripts (uma vez, por usuário)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

# 4. Crie venv
py -3.12 -m venv $HOME\.venvs\hermes

# 5. Ative e instale
$HOME\.venvs\hermes\Scripts\Activate.ps1
pip install --upgrade pip
pip install hermes-agent

# 6. Verifique
hermes --version

⚠️ Erros comuns no Windows nativo

  • Activate.ps1 bloqueado: rode Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
  • PATH errado: reinstale Python marcando "Add to PATH" e abra um PowerShell novo
  • UnicodeEncodeError: exporte $env:PYTHONIOENCODING="utf-8"
  • "Microsoft Visual C++ required": instale VS Build Tools pra compilar wheels

📊 O que NÃO funciona em Windows nativo

  • Algumas tools MCP que dependem de fork() POSIX (≈10%)
  • Containers Docker rodando como tool (precisa Docker Desktop)
  • Caminhos com \ em prompts (use raw strings ou /)

Pra esses casos, WSL2 resolve. Pra tudo o mais — funciona normal.

6

🧙 hermes setup — Wizard interativo

Depois de pip install, o segundo comando que você roda é hermes setup. Ele pergunta tudo que precisa saber e cria ~/.hermes/config.toml + .env automaticamente.

💡 O que o wizard faz

  • •Detecta SO e Python disponíveis
  • •Pergunta provider padrão (OpenRouter, Anthropic, OpenAI, Ollama local)
  • •Valida API key em tempo real (faz request de teste)
  • •Sugere modelo padrão baseado no provider
  • •Pergunta quais canais conectar (TUI, Telegram, Discord, Slack)
  • •Salva secrets no keyring do SO (Keychain/Secret Service/DPAPI)

Output esperado

$ hermes setup

🪽 Hermes Agent Setup Wizard v1.x.x

Detected: Linux 6.x  · Python 3.12.7  · home=/home/you

? Choose default provider:
  ❯ openrouter  (recommended - 200+ models)
    anthropic
    openai
    ollama       (local, no API key)

? Paste OPENROUTER_API_KEY: sk-or-v1-***************
  ✓ key valid · 3 models available

? Default model: anthropic/claude-sonnet-4.5

? Which channels?  (Space to toggle, Enter to confirm)
  [x] tui      (terminal chat)
  [ ] telegram
  [ ] discord
  [ ] slack

? Write config to ~/.hermes/config.toml ? Yes

✓ Config written
✓ Secrets stored in keyring (linux/secret-service)
✓ Run `hermes chat` to start.

Flags úteis

hermes setup --reset            # apaga config e começa do zero
hermes setup --skip-validation  # não testa keys (offline)
hermes setup --profile work     # cria perfil nomeado
hermes doctor                   # verifica config + dependências
hermes config show              # imprime config atual (sem secrets)

💡 Dica — múltiplos perfis

Use --profile pra ter setups diferentes (ex: work, pessoal, cliente-x). Cada perfil tem seu próprio TOML em ~/.hermes/profiles/<nome>.toml. Troque com HERMES_PROFILE=work hermes chat.

✅ Resumo do Módulo

✓
Linux com venv

Caminho recomendado: python3.12 -m venv + pip install hermes-agent

✓
macOS com brew

Apple Silicon nativo, nunca o Python do sistema

✓
WSL2 pra Windows

Melhor performance que Windows nativo + compatibilidade total

✓
Termux pra Android

F-Droid sempre, lembre do termux-wake-lock

✓
Windows nativo se precisar

PowerShell + Python.org, atenção ao ExecutionPolicy

✓
hermes setup como conclusão

Wizard cria config, valida keys e poupa horas de YAML manual

Próximo módulo:

3.2 — 🔑 Providers, canais e migração: OpenRouter, bots e primeira conversa

← Voltar para Trilha Próximo →