Installing Hermes and Your First Session

What the Installer Actually Needs

Hermes keeps its prerequisites short on purpose. On every platform except Windows, the only thing you need pre-installed is Git. The installer handles everything else itself: uv (the Python package manager), Python 3.11, Node.js v22, ripgrep, and ffmpeg are all installed automatically. You do not need to manually set any of these up first.

Supported platforms: macOS, Windows (native, no WSL required), Linux, WSL2, Android via Termux, and NixOS.

Installing

If you are on macOS or Windows and want a graphical app, download the desktop installer from hermes-agent.nousresearch.com and run it.

For a command-line install on Linux, macOS, WSL2, or Android (Termux):

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc   # or ~/.zshrc, depending on your shell

For Windows in native PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

The source step after the shell installer matters more than it looks. The installer adds Hermes to your PATH, but your current terminal session does not know that until you reload your shell config -- this is the single most common "I installed it and the command isn't found" problem.

Choosing a Model Provider

Hermes does not ship with a model baked in -- it talks to whichever LLM provider you configure. This is the one thing in this lesson you must go get yourself before continuing: Hermes does not supply or include any AI model access. You need either an account and API key with a model provider (Anthropic, OpenAI, Google, OpenRouter, or similar -- sign up directly on that provider's own website, generate an API key from their dashboard), or a Nous Portal account if you want to skip managing a provider key yourself. Neither this lesson nor Hermes itself can create that account for you.

Once you have credentials in hand, run the interactive setup:

hermes model

Or, if you signed up for Nous Portal, use one-command setup, which covers authentication for you:

hermes setup --portal

One requirement worth knowing up front: whichever provider you choose needs to support at least 64,000 tokens of context. Most hosted services people reach for -- Claude, GPT, Gemini, Qwen, DeepSeek -- clear that bar comfortably.

If you want to try Hermes without paying for anything first, OpenRouter is worth signing up for specifically because of its free tier: 20+ models with no cost and no credit card required, including capable options like DeepSeek R1 and Llama 3.3 70B. Sign up at openrouter.ai, generate a key, and select a model whose ID ends in :free (for example deepseek/deepseek-r1:free) during hermes model setup. Free-tier rate limits are modest, so it is a way to get a real first session running today, not necessarily what you will run on long-term.

Your First Session

Start the CLI with either:

hermes            # Classic interface
hermes --tui      # Modern TUI (recommended)

Test it with something specific and verifiable rather than a generic "hello" -- for example: "Summarize this repo in 5 bullets and tell me what the main entrypoint is." A vague prompt cannot tell you whether anything is actually working; a specific one can.

You will know it is working when: the startup banner shows the model and provider you selected, the agent replies without errors, any tools it tries to use actually function, and the conversation continues sensibly across more than one exchange.

Resuming a Session

Sessions are not thrown away when you close the terminal. To pick back up where you left off:

hermes --continue    # or hermes -c

Verify it actually reconnected to your previous conversation rather than starting fresh -- ask it something only the prior conversation would know the answer to.

Where Configuration Lives

Two locations matter from day one, and the split between them is deliberate:

• Secrets and tokens go in ~/.hermes/.env
• Everything else (model choice, behavior settings) goes in ~/.hermes/config.yaml

You can set values directly from the command line without hand-editing either file:

hermes config set model anthropic/claude-opus-4.6
hermes config set OPENROUTER_API_KEY sk-or-...

Lesson 4 goes deep on the full configuration system. For now, just know where things live.

Diagnostic Commands

When something looks wrong, these three commands are your first stop, in roughly this order:

hermes doctor                 # Diagnose configuration and dependency issues
hermes sessions list          # View all saved conversations
hermes gateway status         # Check messaging setup (relevant once you reach Advanced)

hermes doctor in particular checks your installation end to end and is almost always the right first move before you start debugging manually.

Common First-Install Problems

Two issues account for most installation trouble, according to Hermes' own troubleshooting documentation:

• Shell PATH not reloaded. You ran the installer but your current terminal still cannot find the hermes command. Fix: source ~/.bashrc or source ~/.zshrc (or just open a new terminal window).
• Python version too old. Hermes requires Python 3.11 or newer. If you have an older system Python and the installer's automatic handling did not cover your case, you may need to upgrade manually.

With a working install, a connected model, and a first successful conversation behind you, the next lesson covers the CLI in enough depth that you will actually be comfortable driving it day to day.