Skip to main content

Hermes on Android with Termux

This is the tested path for running Hermes Agent directly on an Android phone through Termux.

It gives you a working local CLI on the phone, plus the core extras that are currently known to install cleanly on Android.

What is supported in the tested path?​

The tested Termux bundle installs:

  • the Hermes CLI
  • cron support
  • PTY/background terminal support
  • MCP support
  • Honcho memory support
  • ACP support

Concretely, it maps to:

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

What is not part of the tested path yet?​

A few features still need desktop/server-style dependencies that are not published for Android, or have not been validated on phones yet:

  • .[all] is not supported on Android today
  • the voice extra is blocked by faster-whisper -> ctranslate2, and ctranslate2 does not publish Android wheels
  • automatic browser / Playwright bootstrap is skipped in the Termux installer
  • Docker-based terminal isolation is not available inside Termux

That does not stop Hermes from working well as a phone-native CLI agent — it just means the recommended mobile install is intentionally narrower than the desktop/server install.

Option 1: One-line installer​

Hermes now ships a Termux-aware installer path:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

On Termux, the installer automatically:

  • uses pkg for system packages
  • creates the venv with python -m venv
  • installs .[termux] with pip
  • links hermes into $PREFIX/bin so it stays on your Termux PATH
  • skips the untested browser / WhatsApp bootstrap

If you want the explicit commands or need to debug a failed install, use the manual path below.

Option 2: Manual install (fully explicit)​

1. Update Termux and install system packages​

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

Why these packages?

  • python — runtime + venv support
  • git — clone/update the repo
  • clang, rust, make, pkg-config, libffi, openssl — needed to build a few Python dependencies on Android
  • nodejs — optional Node runtime for experiments beyond the tested core path
  • ripgrep — fast file search
  • ffmpeg — media / TTS conversions

2. Clone Hermes​

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

If you already cloned without submodules:

git submodule update --init --recursive

3. Create a virtual environment​

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

ANDROID_API_LEVEL is important for Rust / maturin-based packages such as jiter.

4. Install the tested Termux bundle​

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

If you only want the minimal core agent, this also works:

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

5. Put hermes on your Termux PATH​

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

$PREFIX/bin is already on PATH in Termux, so this makes the hermes command persist across new shells without re-activating the venv every time.

6. Verify the install​

hermes version
hermes doctor

7. Start Hermes​

hermes

Configure a model​

hermes model

Or set keys directly in ~/.hermes/.env.

Re-run the full interactive setup wizard later​

hermes setup

Install optional Node dependencies manually​

The tested Termux path skips Node/browser bootstrap on purpose. If you want to experiment later:

npm install

Treat browser / WhatsApp tooling on Android as experimental until documented otherwise.

Troubleshooting​

No solution found when installing .[all]​

Use the tested Termux bundle instead:

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

The blocker is currently the voice extra:

  • voice pulls faster-whisper
  • faster-whisper depends on ctranslate2
  • ctranslate2 does not publish Android wheels

uv pip install fails on Android​

Use the Termux path with the stdlib venv + pip instead:

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 / maturin complains about ANDROID_API_LEVEL​

Set the API level explicitly before installing:

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

hermes doctor says ripgrep or Node is missing​

Install them with Termux packages:

pkg install ripgrep nodejs

Build failures while installing Python packages​

Make sure the build toolchain is installed:

pkg install clang rust make pkg-config libffi openssl

Then retry:

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

Known limitations on phones​

  • Docker backend is unavailable
  • local voice transcription via faster-whisper is unavailable in the tested path
  • browser automation setup is intentionally skipped by the installer
  • some optional extras may work, but only .[termux] is currently documented as the tested Android bundle

If you hit a new Android-specific issue, please open a GitHub issue with:

  • your Android version
  • termux-info
  • python --version
  • hermes doctor
  • the exact install command and full error output