Brooklyn Nicholson
5ec0667fb3
Add GitHub Actions release channels for signed desktop installers and document the stable/nightly download paths.
5.0 KiB
sidebar_position, title, description
| sidebar_position | title | description |
|---|---|---|
| 2 | Installation | Install Hermes Agent on Linux, macOS, WSL2, or Android via Termux |
Installation
Get Hermes Agent up and running in under two minutes with the one-line installer.
Quick Install
Desktop App (macOS + Windows)
Prefer a native installer? Use the desktop release channel that matches your risk tolerance:
- Stable (recommended): GitHub Releases
- Nightly (rolling prerelease): desktop-nightly
Stable desktop builds ship signed/notarized macOS artifacts and Windows installers with checksum files.
Linux / macOS / WSL2
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Android / Termux
Hermes now ships a Termux-aware installer path too:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
The installer detects Termux automatically and switches to a tested Android flow:
- uses Termux
pkgfor system dependencies (git,python,nodejs,ripgrep,ffmpeg, build tools) - creates the virtualenv with
python -m venv - exports
ANDROID_API_LEVELautomatically for Android wheel builds - installs a curated
.[termux]extra withpip - skips the untested browser / WhatsApp bootstrap by default
If you want the fully explicit path, follow the dedicated Termux guide.
:::warning Windows Native Windows for the CLI installer path is still not supported. Please install WSL2 and run Hermes Agent from there if you want the CLI flow.
For native Windows, use the desktop installers from GitHub Releases. :::
What the Installer Does
The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global hermes command setup, and LLM provider configuration. By the end, you're ready to chat.
Install Layout
Where the installer puts things depends on whether you're installing as a normal user or as root:
| Installer | Code lives at | hermes binary |
Data directory |
|---|---|---|---|
| Per-user (normal) | ~/.hermes/hermes-agent/ |
~/.local/bin/hermes (symlink) |
~/.hermes/ |
Root-mode (sudo curl … | sudo bash) |
/usr/local/lib/hermes-agent/ |
/usr/local/bin/hermes |
/root/.hermes/ (or $HERMES_HOME) |
The root-mode FHS layout (/usr/local/lib/…, /usr/local/bin/hermes) matches where other system-wide developer tools land on Linux. It's useful for shared-machine deployments where one system install should serve every user. Per-user config (auth, skills, sessions) still lives under each user's ~/.hermes/ or explicit HERMES_HOME.
After Installation
Reload your shell and start chatting:
source ~/.bashrc # or: source ~/.zshrc
hermes # Start chatting!
To reconfigure individual settings later, use the dedicated commands:
hermes model # Choose your LLM provider and model
hermes tools # Configure which tools are enabled
hermes gateway setup # Set up messaging platforms
hermes config set # Set individual config values
hermes setup # Or run the full setup wizard to configure everything at once
Prerequisites
The only prerequisite is Git. The installer automatically handles everything else:
- uv (fast Python package manager)
- Python 3.11 (via uv, no sudo needed)
- Node.js v22 (for browser automation and WhatsApp bridge)
- ripgrep (fast file search)
- ffmpeg (audio format conversion for TTS)
:::info
You do not need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what's missing and installs it for you. Just make sure git is available (git --version).
:::
:::tip Nix users If you use Nix (on NixOS, macOS, or Linux), there's a dedicated setup path with a Nix flake, declarative NixOS module, and optional container mode. See the Nix & NixOS Setup guide. :::
Manual / Developer Installation
If you want to clone the repo and install from source — for contributing, running from a specific branch, or having full control over the virtual environment — see the Development Setup section in the Contributing guide.
Troubleshooting
| Problem | Solution |
|---|---|
hermes: command not found |
Reload your shell (source ~/.bashrc) or check PATH |
API key not set |
Run hermes model to configure your provider, or hermes config set OPENROUTER_API_KEY your_key |
| Missing config after update | Run hermes config check then hermes config migrate |
For more diagnostics, run hermes doctor — it will tell you exactly what's missing and how to fix it.