Skip to main content

Hermes on Android with Termux

Tier 2 platform

Termux (Android) is a Tier 2 platform. The installer script and documentation here are maintained on a best-effort basis only. Commits to main may break these packages at any point in time.

Hermes Agent can run 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
  • Telegram gateway support (manual / best-effort background runs)
  • 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
  • Android may still suspend Termux background jobs, so gateway persistence is best-effort rather than a normal managed service

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.

Community-maintained native pkg option​

Contributor-operated distribution

This APT repository is community-maintained by @adybag14-cyber and is not an official NousResearch distribution. NousResearch does not build, sign, host, or audit these packages. Enabling the repository means trusting the contributor-operated repository and its signing key. Termux itself remains a Tier 2 / best-effort platform.

For users who prefer a native package-manager install rather than building Python/Rust dependencies on the phone, a community-maintained APT repository is available. The repository bootstrap and packaging sources are published in adybag14-cyber/termux-python, with the Hermes package build in adybag14-cyber/termux-hermes.

Install the repository key/source and Hermes with:

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

The repository signing-key fingerprint currently documented by the community distribution is:

EAD24A2124EFA7393A78B7B14699F966313F7A6B

APT-managed Hermes installs are marked with install method apt. Hermes therefore does not run its Git self-updater against package-owned files; use the package manager instead:

pkg update
pkg upgrade hermes-agent

Packaging/repository/signing problems for this option should be reported to the community packaging repositories above. Hermes runtime bugs can still be reported here, keeping in mind that Android/Termux support is best-effort.

Option 1: One-line installer​

Hermes now ships a Termux-aware installer path:

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

On Termux, the installer automatically:

  • uses pkg for system packages
  • creates the venv with python -m venv
  • attempts the broad .[termux-all] extra first and falls back to the smaller .[termux] extra (then a base install) — the curl installer matches this order automatically
  • 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 https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

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 with browser tooling later, what you need depends on which backend you use:

  • Cloud browser providers (Browserbase, Browser Use, Firecrawl) host their own Chromium, so Node.js alone is enough — agent-browser resolves lazily via npx agent-browser on first use:

    pkg install nodejs-lts

  • Local browser automation on Termux needs a real agent-browser install — the bare npx fallback is deliberately rejected in local mode as too fragile to advertise as ready:

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

The browser tool automatically includes Termux directories (/data/data/com.termux/files/usr/bin) in its PATH search, so agent-browser and npx are discovered without any extra PATH configuration.

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] and .[termux-all] are currently documented as the tested Android bundles

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