Installation Guide

Install Hermes Agent on Linux, macOS, or WSL2

Quick Install

The recommended way is to use the official one-line installer. Supports Linux, macOS, and WSL2 (Windows Subsystem for Linux 2).

bash 
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Windows users: Native Windows is not supported. Please install WSL2 first, then run the command above in a WSL2 terminal.

After installation, reload your shell:

source ~/.bashrc    # if using zsh: source ~/.zshrc

System Requirements

Item Requirement
OS Linux, macOS, WSL2 (native Windows is not supported)
Prerequisites Git (the installer will handle Python, Node.js, and other dependencies automatically)
Network Access to GitHub and model API endpoints required
Recommended HW A $5/month VPS is sufficient; GPU clusters and Serverless are also supported

Verify Installation

After installation, verify with:

hermes --version

If you see a version number, the installation was successful. You can also run the diagnostic tool:

hermes doctor

Configuration

Hermes Agent requires at least one LLM provider. Run the setup wizard:

hermes setup

The setup wizard guides you through:

  1. Choose a model provider — supports OpenRouter (200+ models), OpenAI, Anthropic, Nous Portal, Google Gemini, and more
  2. Enter API Key — at least one provider key is required
  3. Configure messaging platforms (optional) — Telegram, Discord, Slack, etc.
  4. Enable tools — select which tool sets to enable

You can also configure individually:

hermes model        # choose a model
hermes tools        # configure tools
hermes config set   # set a single config item

Common Commands

Command Description
hermes Start an interactive CLI chat
hermes setup Run the full setup wizard
hermes model Switch model provider and model
hermes tools Configure enabled tools
hermes gateway Start the messaging gateway (Telegram, etc.)
hermes update Update to the latest version
hermes doctor Diagnose issues

Troubleshooting

Issue: curl command fails

Possible causes and solutions:

  • Network issues: Make sure you can access GitHub. Users behind a firewall may need to set a proxy: export https_proxy=http://your-proxy:port
  • curl not installed: Run sudo apt install curl (Ubuntu/Debian) or brew install curl (macOS)

Issue: hermes command not found

  • Make sure you have run source ~/.bashrc or source ~/.zshrc
  • Check that ~/.local/bin is in your PATH
  • Try reopening your terminal

Issue: Python-related errors

  • Hermes requires Python 3.10+. The install script handles this automatically, but if installing manually, make sure the Python version is correct
  • Try running hermes doctor for automatic diagnostics

Issue: WSL2 installation problems

  • Make sure your WSL2 version is up to date: wsl --update
  • Ubuntu 22.04+ distribution is recommended
  • Run sudo apt update && sudo apt install -y curl git in WSL2 before running the install script

Issue: Model API connection fails

  • Verify your API Key is correct: hermes config get provider.api_key
  • Check that your network can reach the corresponding API endpoint
  • Try using OpenRouter as a unified gateway (supports 200+ models)

Getting More Help