Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Hermes no Android, com Termux

Plataforma de nível 2

O Termux (Android) é uma plataforma de nível 2. O script de instalação e esta documentação são mantidos apenas por esforço. Commits na main podem quebrar esses pacotes a qualquer momento.

O Hermes Agent roda direto num celular Android pelo Termux.

Você fica com uma CLI local funcionando no telefone, mais os extras principais que hoje se sabe que instalam sem problema no Android.

O que o caminho testado suporta​

O pacote testado do Termux instala:

  • a CLI do Hermes
  • suporte a cron
  • suporte a terminal em PTY e em segundo plano
  • suporte ao gateway do Telegram (execução em segundo plano manual, por esforço)
  • suporte a MCP
  • suporte à memória Honcho
  • suporte a ACP

Na prática, corresponde a:

python -m pip install -e '.[termux]' -c constraints-termux.txt

O que ainda não faz parte do caminho testado​

Alguns recursos ainda dependem de bibliotecas de desktop ou servidor que não são publicadas para Android, ou que ainda não foram validadas em celular:

  • .[all] não é suportado no Android hoje
  • o extra voice está travado pelo faster-whisper -> ctranslate2, e o ctranslate2 não publica pacotes para Android
  • o instalador do Termux pula a preparação automática de navegador e Playwright
  • isolamento de terminal por Docker não existe dentro do Termux
  • o Android pode suspender processos em segundo plano do Termux, então a persistência do gateway é por esforço, não um serviço gerenciado normal

Nada disso impede o Hermes de funcionar bem como agente de linha de comando no celular — só significa que a instalação recomendada no telefone é, de propósito, mais enxuta que a de desktop ou servidor.

Opção nativa por pkg, mantida pela comunidade​

Distribuição operada por colaborador

Este repositório APT é mantido pela comunidade, por @adybag14-cyber, e não é uma distribuição oficial da NousResearch. A NousResearch não compila, não assina, não hospeda e não audita esses pacotes. Habilitar o repositório significa confiar nele e na chave de assinatura dele. O Termux continua sendo plataforma de nível 2, por esforço.

Para quem prefere instalar por gerenciador de pacotes nativo, em vez de compilar dependências de Python e Rust no celular, existe um repositório APT mantido pela comunidade. Os fontes do repositório e do empacotamento estão em adybag14-cyber/termux-python, e o pacote do Hermes em adybag14-cyber/termux-hermes.

Instale a chave, a fonte do repositório e o Hermes com:

curl -fsSL https://raw.githubusercontent.com/adybag14-cyber/termux-python/main/scripts/setup_apt_repo.sh | bash
pkg install hermes-agent

A impressão digital da chave de assinatura documentada hoje pela distribuição da comunidade é:

EAD24A2124EFA7393A78B7B14699F966313F7A6B

Instalações gerenciadas por APT são marcadas com o método apt. Por isso o Hermes não roda o autoatualizador de Git em cima de arquivos que pertencem ao pacote; use o gerenciador:

pkg update
pkg upgrade hermes-agent

Problemas de empacotamento, repositório ou assinatura devem ser relatados nos repositórios da comunidade acima. Bugs do Hermes em si continuam sendo reportados no projeto, lembrando que o suporte a Android e Termux é por esforço.

Opção 1: instalador de uma linha​

O Hermes já traz um caminho de instalação que reconhece o Termux:

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

No Termux, o instalador automaticamente:

  • usa o pkg para os pacotes de sistema
  • cria o ambiente virtual com python -m venv
  • tenta primeiro o extra amplo .[termux-all] e recua para o menor .[termux] (e depois para a instalação básica) — o instalador segue essa ordem sozinho
  • cria o link do hermes em $PREFIX/bin, para ele continuar no PATH do Termux
  • pula a preparação de navegador e WhatsApp, que não foi testada

Se você quer os comandos explícitos, ou precisa investigar uma instalação que falhou, use o caminho manual abaixo.

Opção 2: instalação manual, passo a passo​

1. Atualize o Termux e instale os pacotes de sistema​

pkg update
pkg install -y git python clang rust make pkg-config libffi openssl nodejs ripgrep ffmpeg

Por que cada um:

  • python — runtime e suporte a ambiente virtual
  • git — clonar e atualizar o repositório
  • clang, rust, make, pkg-config, libffi, openssl — necessários para compilar algumas dependências Python no Android
  • nodejs — runtime opcional, para experimentos além do núcleo testado
  • ripgrep — busca rápida em arquivos
  • ffmpeg — conversões de mídia e síntese de voz

2. Clone o Hermes​

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

3. Crie um ambiente virtual​

python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install --upgrade pip setuptools wheel

O ANDROID_API_LEVEL é importante para pacotes baseados em Rust e maturin, como o jiter.

4. Instale o pacote testado do Termux​

python -m pip install -e '.[termux]' -c constraints-termux.txt

Se você quer só o agente mínimo, isto também funciona:

python -m pip install -e '.' -c constraints-termux.txt

5. Coloque o hermes no PATH do Termux​

ln -sf "$PWD/venv/bin/hermes" "$PREFIX/bin/hermes"

O $PREFIX/bin já está no PATH do Termux, então o comando hermes passa a existir em qualquer shell novo, sem precisar ativar o ambiente virtual toda vez.

6. Confira a instalação​

hermes --version
hermes doctor

7. Comece​

hermes

Configurar um modelo​

hermes model

Ou defina as chaves direto em ~/.hermes/.env.

Rodar o assistente completo depois​

hermes setup

Instalar as dependências de Node na mão​

O caminho testado do Termux pula a preparação de Node e navegador de propósito. Se você quiser experimentar automação de navegador depois, o que instalar depende do backend:

  • Provedores de navegador na nuvem (Browserbase, Browser Use, Firecrawl) hospedam o próprio Chromium, então basta o Node.js — o agent-browser é resolvido sob demanda, via npx agent-browser, no primeiro uso:

    pkg install nodejs-lts

  • Automação de navegador local no Termux precisa de uma instalação de verdade do agent-browser — o recuo para npx puro é recusado de propósito no modo local, por ser frágil demais para ser anunciado como pronto:

    pkg install nodejs-lts
    npm install -g agent-browser && agent-browser install

A ferramenta de navegador já inclui os diretórios do Termux (/data/data/com.termux/files/usr/bin) na busca do PATH, então o agent-browser e o npx são encontrados sem configuração extra.

Trate as ferramentas de navegador e WhatsApp no Android como experimentais, até que a documentação diga o contrário.

Resolução de problemas​

No solution found ao instalar .[all]​

Use o pacote testado do Termux:

python -m pip install -e '.[termux]' -c constraints-termux.txt

O bloqueio hoje é o extra voice:

  • voice puxa o faster-whisper
  • faster-whisper depende do ctranslate2
  • ctranslate2 não publica pacotes para Android

uv pip install falha no Android​

Use o caminho do Termux, com o venv da biblioteca padrão e o pip:

python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e '.[termux]' -c constraints-termux.txt

jiter ou maturin reclamam do ANDROID_API_LEVEL​

Defina o nível da API antes de instalar:

export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install -e '.[termux]' -c constraints-termux.txt

O hermes doctor diz que falta ripgrep ou Node​

Instale pelos pacotes do Termux:

pkg install ripgrep nodejs

Falhas de compilação ao instalar pacotes Python​

Confira se as ferramentas de compilação estão instaladas:

pkg install clang rust make pkg-config libffi openssl

Depois tente de novo:

python -m pip install -e '.[termux]' -c constraints-termux.txt

Limitações conhecidas no celular​

  • o backend Docker não existe
  • a transcrição de voz local pelo faster-whisper não existe no caminho testado
  • a preparação da automação de navegador é pulada de propósito pelo instalador
  • alguns extras opcionais podem funcionar, mas só .[termux] e .[termux-all] estão documentados hoje como os pacotes testados para Android

Se você encontrar um problema novo específico do Android, abra uma issue no GitHub com:

  • sua versão do Android
  • a saída de termux-info
  • python --version
  • hermes doctor
  • o comando exato de instalação e a saída de erro completa