How to get Hermes

An assistant that runs on your own machine, takes a job and carries it through. Installing takes minutes, and it isn't for sale.

14 minLesson 8 of 90 of 8 steps

Hermes is an agent. The difference from the chat is that it doesn't just talk: it runs on your computer, can run commands, read files and push a job forward step by step until it's done.

First, two things people always ask. You don't buy Hermes from us: it's a free open-source tool made by other developers, not an IranRouter product. What costs money is the model Hermes uses, and that comes off your wallet.

So you need three things: Hermes itself, an ir- key, and some balance.

Before installing

Hermes installs on Linux, macOS, WSL2 and Windows. A Desktop version for macOS and Windows is on its own site. The model you pick must have at least 64K tokens of context; that figure is on each model's page.

Step one: make a key

A key for Hermes0 of 5 steps

  1. Go to API keys and press New key.
  2. Name it "Hermes laptop".
  3. Set "Where should this key's spend come from?" to Credit (pay as you go).
  4. Set a Monthly cap. A small number is fine to begin.
  5. Copy the key and tick "I've stored the key somewhere safe". It's shown only this once.
Create a key

Step two: install Hermes

On Linux, macOS or WSL2, open a terminal and run:

Shell
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc   # or ~/.zshrc

On Windows, in PowerShell:

powershell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
If the installer can't connect, the problem is reaching the install server, not your key. Try again later or on another connection.

Step three: connect it to IranRouter

Open ~/.hermes/config.yaml and write the model section like this. Replace ir-... with your key, and take the model id from the models page:

YAML
model:
  provider: custom
  default: anthropic/claude-sonnet-4.6
  base_url: https://iranrouter.com/v1
  api_key: ir-...

If you'd rather not edit the file, run hermes model, choose the custom endpoint option, and give the same address and key.

Step four: try it

Shell
hermes --tui

Write "Hello, what files are in this folder?" and wait for the answer. If something goes wrong, hermes doctor finds it.

Make sure it went through us0 of 3 steps

  1. You should see that request with the model name, tokens and cost.
  2. If nothing's there, base_url or the key isn't set correctly.
Open the logs

What an agent costs

Even a simple job can make an agent send many requests, each carrying the whole history again. So it costs more than a normal conversation. That's why we put a monthly cap on this key: if something runs away, spending stops at the number you chose.

Start with a mid-range model for ordinary work, and bring in a strong one only when the job is really hard.

What you learned

  • Hermes is free and open source; only model use comes off your wallet.
  • Four lines in config.yaml connect it to IranRouter.
  • Always put a cap on its key.
When you get stuckOne small id and one page clear most problems in a minute.Done, next lesson