b7fe7ed7bd
User hit a real failure case: their system Git was in a half-installed state
(can neither uninstall nor reinstall) and winget refused to work around it.
We were one step away from shipping an installer that would have left users
with exactly the problem he already had.
What other agents do (reality check):
- Claude Code: requires pre-installed Git; breaks if user doesn't have it.
- OpenCode, Codex: don't need bash at all — PowerShell-first design.
- Cline: uses whatever shell VSCode is configured with; installs nothing.
None of them solve the "broken system Git" problem. We need to own our Git.
Changes:
- scripts/install.ps1::Install-Git: dropped winget path entirely. Now:
(1) use existing git if present; (2) download portable MinGit from the
official git-for-windows GitHub release to %LOCALAPPDATA%\hermes\git.
No winget, no admin, no Windows installer registry, no system impact.
- Added %LOCALAPPDATA%\hermes\git\{cmd,usr\bin} to User PATH so git + bash
+ POSIX coreutils (which, env, grep, …) resolve in fresh shells.
- tools/environments/local.py::_find_bash: reorder so Hermes' portable
MinGit install is checked BEFORE falling through to shutil.which("bash")
or system install locations. This way a broken system Git can't
hijack the bash lookup.
- README + installation docs reworded to reflect the new story: "portable
Git Bash, isolated from any system install, recoverable via rm -rf if it
ever breaks."
Recoverability: if Hermes' Git install ever breaks, ``Remove-Item %LOCALAPPDATA%\hermes\git``
and re-run the installer — no system impact, no uninstall drama, no winget
to fight with.
6.8 KiB
| sidebar_position | title | description |
|---|---|---|
| 2 | Installation | Install Hermes Agent on Linux, macOS, WSL2, native Windows, or Android via Termux |
Installation
Get Hermes Agent up and running in under two minutes with the one-line installer.
Quick Install
Linux / macOS / WSL2
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Windows (native, PowerShell)
Open PowerShell and run:
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
The installer handles everything: uv, Python 3.11, Node.js 22, ripgrep, ffmpeg, and a portable Git Bash (MinGit — a slim, self-contained Git for Windows distribution that Hermes uses for shell commands). It clones the repo under %LOCALAPPDATA%\hermes\hermes-agent, creates a virtualenv, and adds hermes to your User PATH. Restart your terminal (or open a new PowerShell window) after the install so PATH picks up.
How Git is handled:
- If
gitis already on your PATH, the installer uses your existing install. - Otherwise it downloads portable MinGit (~45MB, from the official
git-for-windowsGitHub release) and unpacks it to%LOCALAPPDATA%\hermes\git. No admin rights required. Completely isolated — it won't interfere with any system Git install, broken or otherwise.
Why not use winget? Earlier designs auto-installed Git via winget install Git.Git, but winget fails badly when a system Git install is in a partial or broken state (exactly when users need the installer to just work). The portable MinGit approach sidesteps winget, the Windows installer registry, and any existing system Git entirely. If the Hermes Git install itself ever breaks, Remove-Item %LOCALAPPDATA%\hermes\git and re-run the installer — no system impact, no uninstall drama.
The installer also sets HERMES_GIT_BASH_PATH to the located bash.exe so Hermes resolves it deterministically in fresh shells.
If you prefer WSL2, the Linux installer above works inside it; both native and WSL installs can coexist without conflict (native data lives under %LOCALAPPDATA%\hermes, WSL data lives under ~/.hermes).
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.
:::note Windows Feature Parity
Everything except the browser-based dashboard chat terminal runs natively on Windows:
- CLI (
hermes chat,hermes setup,hermes gateway, …) — native, uses your default terminal - Gateway (Telegram, Discord, Slack, …) — native, runs as a background PowerShell process
- Cron scheduler — native
- Browser tool — native (Chromium via Node.js)
- MCP servers — native (stdio and HTTP transports both supported)
- Dashboard
/chatterminal pane — WSL2 only (uses a POSIX PTY; native Windows has no equivalent). The rest of the dashboard (sessions, jobs, metrics) works natively — only the embedded PTY terminal tab is gated.
Set HERMES_DISABLE_WINDOWS_UTF8=1 in your environment if you hit an encoding-related bug and want to fall back to the legacy cp1252 stdio path (useful for bisecting).
:::
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.