Hermes Agent on GitHub: Repo, Install & How It Works

Steps

1. 01

   Find the official repository

   The canonical source lives at github.com/NousResearch/hermes-agent, built by Nous Research and licensed MIT. Be careful with look-alikes: several third-party 'awesome-hermes-agent' lists and doc mirrors exist — verify any command against the official NousResearch repo before running it.

   # Official repo
   https://github.com/NousResearch/hermes-agent

2. 02

   Install with the one-line installer (recommended)

   The fastest path is the official installer, which provisions the full toolchain (uv, Python 3.11, Node.js, ripgrep, ffmpeg, and a portable Git if needed) and clones the code for you. On Linux/macOS/WSL2/Termux use the shell script; on native Windows use PowerShell. After it finishes, reload your shell and run hermes.

   # Linux / macOS / WSL2 / Termux
   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
   
   # Windows (native, PowerShell)
   iex (irm https://hermes-agent.nousresearch.com/install.ps1)
   
   # Then reload your shell and start it
   source ~/.bashrc   # or: source ~/.zshrc
   hermes

3. 03

   Or clone the repository directly

   If you prefer to work from source — to read the code, pin a branch, or contribute — clone the repo yourself. The installer normally checks out the code under your Hermes home directory (see the next step); cloning manually gives you the same tree to inspect. Building/running from a manual clone still requires the same toolchain the installer sets up.

   git clone https://github.com/NousResearch/hermes-agent.git
   cd hermes-agent
   # Then follow the repo's README / docs to set up the environment
   # (the installer automates uv + Python 3.11 + Node + deps)

4. 04

   Know where Hermes stores its data

   Hermes keeps its home directory (config, memory, skills, and the working checkout) at ~/.hermes on Linux/macOS/WSL2, and %LOCALAPPDATA%\hermes on native Windows. The code checkout typically lives at ~/.hermes/hermes-agent. You can override the location with the HERMES_HOME environment variable before installing.

   # Default data + checkout location
   ~/.hermes                 # Linux / macOS / WSL2
   %LOCALAPPDATA%\hermes      # native Windows
   ~/.hermes/hermes-agent    # the cloned code checkout

5. 05

   Understand the repository layout

   The repo is organized by subsystem. The top-level folders below are what you see in the GitHub file browser (read 2026-06-20). The Python entry points (cli.py, run_agent.py, setup.py) sit at the root alongside packaging and container files (pyproject.toml, Dockerfile, docker-compose.yml, flake.nix, .env.example).

   # Top-level folders (abridged)
   agent/         # core agent loop
   hermes_cli/    # the `hermes` command-line interface
   gateway/       # messaging gateway (Telegram, Discord, Slack, ...)
   tui_gateway/   ui-tui/   web/   website/   # interfaces
   providers/     # model provider integrations
   skills/  optional-skills/   # skill library
   cron/          # scheduled automations
   docker/  nix/  packaging/    # deploy / packaging
   tools/  optional-mcps/  plugins/  locales/  docs/  tests/

6. 06

   Run it and see the commands

   Once installed, start Hermes by running hermes. The core commands (verbatim from the official README) cover choosing a model, configuring tools, the gateway, and diagnostics. For a guided first run, hermes setup walks through everything at once — see our dedicated Hermes Agent setup guide.

   hermes              # start chatting interactively
   hermes model        # choose your LLM provider and model
   hermes setup        # full setup wizard
   hermes gateway      # start the messaging gateway
   hermes doctor       # diagnose issues
   hermes update       # update to the latest version

Troubleshooting

Not sure which 'hermes' repo or site is official

The official repository is github.com/NousResearch/hermes-agent and the official installer domain is hermes-agent.nousresearch.com. Third-party 'awesome-hermes-agent' lists, doc mirrors, and unaffiliated sites exist — do not run install commands from them. When in doubt, start from the GitHub repo's README.

hermes: command not found after the installer finishes

The installer adds Hermes to your PATH via your shell profile, but the current shell session has not reloaded it. Run source ~/.bashrc (or source ~/.zshrc), or open a new terminal, then try hermes again. On native Windows, open a new PowerShell window.

You want to inspect the code before trusting the installer

Clone the repo first (git clone https://github.com/NousResearch/hermes-agent.git) and read install.sh, cli.py, and the README. The installer is a shell script you can review before piping it to bash; you can also download it and run it after inspection rather than using curl | bash directly.

The install pulls a large toolchain you did not expect

The installer provisions uv, Python 3.11, Node.js, ripgrep, ffmpeg, and (on Windows, if needed) a ~45MB portable Git — by design, so Hermes is self-contained. If you already have these, the installer detects and reuses them. To minimize footprint, review install.sh options (e.g. flags to skip the browser/Playwright step) on the official repo.