1. Which Install Method Should You Use?
Hermes Agent ships five install paths — all land on the same agent core and the same config in ~/.hermes/. Pick by how you like to work. New to the terminal? Use the desktop app. Live in a shell? Use the install script. Want it in a Python project or a container? pip or Docker. If you want the bigger picture first, our Hermes Agent guide explains what it is and why the architecture is worth a look.
| Method | Best for | Command |
|---|---|---|
| Desktop app | Beginners; a GUI with no terminal | Download the installer from the official site |
| CLI script | Mac / Linux / WSL2, fastest terminal setup | curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash |
| Windows PowerShell | Native Windows without WSL2 | iex (irm https://hermes-agent.nousresearch.com/install.ps1) |
| pip | Python users; put it in a venv/project | pip install hermes-agent |
| Docker | Isolated / reproducible / server deploys | docker pull nousresearch/hermes-agent:latest |
2. Install Hermes Agent on macOS
Two options. For a GUI, download the Hermes Desktop installer from hermes-agent.nousresearch.com and run it. For the terminal (CLI + desktop share one core and memory):
Standard caution: piping a script into bash runs remote code. Read the script first (curl -fsSL …/install.sh | less) if your threat model calls for it, or install from the GitHub repo.
3. Install Hermes Agent on Windows
Two supported paths. Native PowerShell (no WSL2 needed) for the CLI:
Or install the Hermes Desktop EXE from the official site for a full GUI. If you prefer a Linux-native environment, open WSL2 (Ubuntu) and run the macOS/Linux install.shcommand from the section above — that's the most battle-tested path for the Python runtime.
4. Install Hermes Agent on Linux (and WSL2)
The same one-line installer covers Linux, WSL2, and even Android via Termux:
5. Install Hermes Agent with pip (Python Package)
Since May 2026, Hermes Agent is on PyPI. Install it into a virtual environment so it doesn't collide with other Python projects:
The pip route is handy if you want to pin Hermes in a project's dependencies or run it inside an existing Python toolchain.
6. Run Hermes Agent with Docker
For an isolated or server deployment, pull the official image and mount a volume so your config and memory persist between runs:
On Apple Silicon, add --platform linux/arm64 to the pull. Docker is also one of Hermes's execution sandboxes — useful when you want the agent to run untrusted tasks in isolation.
7. First Run: Pick a Model and Start
After any install method, configure a provider, then start the agent. Hermes is model-agnostic — bring your own API key (OpenAI, Anthropic, OpenRouter, or a compatible endpoint), or use Nous Portal:
Secrets live in ~/.hermes/.env and settings in ~/.hermes/config.yaml. Hermes needs a model with at least a 64,000-token context window, so pick a provider/model that meets that.
8. Optional: Voice, Messaging Gateways, and Health Checks
- • Voice mode:
cd ~/.hermes/hermes-agent && uv pip install --python ./venv/bin/python -e ".[voice]", then/voice onin the CLI. - • Messaging gateways (Telegram, Discord, Slack, WhatsApp, Signal):
hermes gateway setup. - • Diagnose problems:
hermes doctor. - • Update to the latest version:
hermes update. - • List saved sessions:
hermes sessions list.
9. Troubleshooting Common Install Issues
- •
hermes: command not found: reload your shell —source ~/.bashrcorsource ~/.zshrc— or open a new terminal. - • Context-window error on first message: your model is below the 64k-token minimum; pick a larger-context model with
hermes model. - • Windows PowerShell blocks the script: run PowerShell as Administrator, or use WSL2 with the Linux installer.
- • Anything else: run
hermes doctor— it diagnoses most config and provider issues.
Deciding whether Hermes is even the right agent for you? See our Hermes Agent vs OpenClaw comparison.
Install worked but something else is failing? Our Hermes Agent troubleshooting guide covers the common errors and hermes doctor --fix. And if Hermes turns out not to fit, see the best Hermes Agent alternatives.
10. Frequently Asked Questions
Is Hermes Agent free to install?
Yes. Hermes Agent is MIT-licensed and free to download, install, and self-host. You only pay for the model inference you use, via your own API keys or a Nous Portal subscription.
Can I install Hermes Agent on Windows without WSL2?
Yes — use the native PowerShell installer (iex (irm …/install.ps1)) or the Hermes Desktop EXE. WSL2 is optional and mainly preferred if you want a Linux-native Python environment.
How do I install Hermes Agent with pip?
Run pip install hermes-agent (ideally inside a virtual environment), then start it with hermes --tui. PyPI support was added in May 2026.
Where is Hermes installed and how do I remove it?
Config and data live in ~/.hermes/ (secrets in .env, settings in config.yaml). To remove a pip install, pip uninstall hermes-agent; for the script install, delete ~/.hermes/ and remove the PATH line the installer added to your shell rc file.