ع
🤖 AI Agents

How to Set Up Hermes Desktop: Installation Guide for Windows, macOS & Linux

From download to your first working conversation — the honest setup guide: what gets installed, how to pick a model provider, and the five problems that trip up most beginners.

Beginner10 min read

What you'll be able to do by the end

  • Install Hermes Desktop (or the CLI) on your system in minutes
  • Connect a model provider — subscription or API key
  • Run a first conversation that proves everything works
  • Fix the most common setup failures yourself

Before you start

  • A computer running Windows, macOS or Linux with internet access
  • Git installed (the only real prerequisite — check with git --version)
  • A way to use an AI model: a subscription login (e.g. Nous Portal) or an API key from any major provider

Most setup guides assume too much or promise too little. This one has a single goal: a working Hermes Agent on your machine, verified by an actual conversation — plus the fixes for the handful of things that commonly go wrong.

What you’re installing

Two applications, one brain:

  • Hermes Desktop — the native app for Windows, macOS and Linux: streaming chat, session list, drag-and-drop files, notifications.
  • The Hermes CLI — the same agent in your terminal, with commands like hermes, hermes model and hermes doctor.

The recommended installer gives you both. Under the hood it also sets up Python, Node.js, ripgrep and ffmpeg — but you never manage those directly.

Requirements, honestly

The only true prerequisite is Git (git --version to confirm). Everything else the installer handles. On Linux, add curl and xz-utils (present on most systems), and build-essential if you want the desktop app. You need one way to reach an AI model: a subscription login such as Nous Portal, or an API key from OpenRouter, Anthropic, OpenAI, Google and dozens more — and whichever model you choose must support at least 64K tokens of context (virtually all hosted models do).

Hardware-wise: if your computer runs a modern browser comfortably, hosted-model setups will fly. Local models are the only path with real hardware demands — and they’re optional, not required.

Step-by-step

1. Install. Download the Hermes Desktop installer and run it — or CLI-only via the commands in the steps section above.

2. Reload your terminal, so the new hermes command is visible.

3. Connect a model. Run:

hermes model

and pick a provider. The fastest route for beginners:

hermes setup --portal

One OAuth login → 300+ models + built-in web search, image generation and TTS. No key management at all.

4. First test. Run hermes and give it a verifiable task:

Check my current directory and tell me which file looks like the main entrypoint.

Success looks like: the banner shows your model, the agent replies without error, it reads a real file, and the conversation continues past one turn. That’s the whole checklist.

5. Verify persistence. Exit, then run hermes --continue. Your last session should return intact. Sessions surviving restarts is what makes longer projects possible.

When something breaks

Before searching forums, ask the agent’s own doctor:

hermes doctor

It names the missing piece precisely. The classic three, solved:

Symptom Fix
hermes: command not found Reload the terminal / fix PATH
API key not set hermes model — finish provider setup
Config looks wrong after update hermes config check then hermes config migrate

And the meta-rule from the official docs worth stealing: if Hermes cannot complete a normal chat, do not add more features yet. One clean conversation first; gateway, cron, skills and everything else layer on top of a working floor.

Next steps

Your agent works locally now. Put it in your pocket with Hermes + Telegram, learn daily driving skills in Hermes Agent for Beginners, or go straight to workflows and scheduling with Skills, Models & Automation.

If you’re still weighing agents against plain chatbots, What Is Hermes Agent? settles it in eight minutes.

Steps

  1. Step 1: Pick your install path

    Two supported routes. **Route A (recommended for beginners):** download the Hermes Desktop installer from hermes-agent.nousresearch.com and run it — it installs both the desktop app and the `hermes` command-line tool together. **Route B (command line only):** run the shell installer in your terminal. On Linux/macOS/WSL2: `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`. On native Windows, in PowerShell: `iex (irm https://hermes-agent.nousresearch.com/install.ps1)`.

    Note: Started CLI-only and changed your mind? Run `hermes desktop` afterwards — it sets up and launches the desktop app.

  2. Step 2: Let the installer do its job

    The installer handles everything automatically: Python 3.11 and Node.js v22 via uv, ripgrep, ffmpeg, the repository checkout, the virtual environment, and the global `hermes` command. You don't install Python or Node yourself — that's the point. When it finishes, reload your terminal (`source ~/.bashrc` or restart it).

    Note: On Linux the desktop app additionally needs build tools: sudo apt install build-essential on Debian/Ubuntu.

  3. Step 3: Choose a provider and model

    This is the single most important step — it decides what Hermes 'thinks' with. Run `hermes model` and follow the wizard. Easiest path: Nous Portal (`hermes setup --portal`) — one OAuth login covers 300+ models plus built-in tools like web search, image generation and text-to-speech, no API keys to juggle. Prefer pay-per-token? OpenRouter is one key across many models; Anthropic, OpenAI and Google take their own keys; local models work through Ollama or llama.cpp.

    Note: One hard requirement: the model needs at least 64K tokens of context. Nearly every hosted model passes easily; if you self-host, raise the context flag accordingly.

  4. Step 4: Understand where settings live

    Two files, two jobs: secrets and API keys go in `~/.hermes/.env`; normal settings live in `~/.hermes/config.yaml`. You rarely touch either by hand — `hermes config set KEY VALUE` writes to the right file automatically. This split keeps keys out of anything you might share or sync.

    Note: `hermes setup` reruns the full wizard anytime; `hermes config get KEY` inspects one value.

  5. Step 5: Run the first successful test

    Type `hermes` and press Enter. The welcome banner should show your chosen model and available tools. Give it a task that proves tool access, like "Check my current directory and tell me which project file looks like the main entrypoint." If it answers and can read files, you're done — that's the whole bar.

    Note: Then verify sessions persist: exit, run `hermes --continue`, and confirm your last conversation returns intact.

  6. Step 6: Confirm health when something feels off

    `hermes doctor` is the official diagnostic: it reports exactly what's missing — PATH entries, keys, dependencies — and how to fix each item. Run it before guessing at forum posts.

    Note: `hermes update` keeps the installation current; Hermes detects your install method and prints the matching update command.

Common mistakes — and how to avoid them

Mistake'hermes: command not found' right after installing.

Do this insteadReload your terminal or check PATH — the installer tells you; source ~/.bashrc (or reopen PowerShell) before assuming failure.

Mistake'API key not set' on first launch.

Do this insteadRun hermes model and complete provider configuration, or set the key directly: hermes config set OPENROUTER_API_KEY your_key.

MistakePasting an API key into config.yaml.

Do this insteadKeys belong in ~/.hermes/.env only. Use hermes config set and the value routes itself to the correct file.

MistakeChoosing the biggest local model on a small machine and blaming Hermes when it crawls.

Do this insteadMatch the model to your hardware, keep the 64K context requirement in mind, and start with a hosted provider — optimize later.

MistakeSkipping verification and building automations on top of a broken base.

Do this insteadOne clean chat first, then layers. If base chat doesn't work, nothing above it will — fix the floor before decorating.

❓ Frequently asked questions

Do I need Hermes Desktop specifically, or is the CLI enough?

Both drive the same agent core. The desktop app adds streaming chat UI, session list, command palette, drag-and-drop files and notifications; the CLI does everything through the terminal. Many people install both from the same installer and switch freely — settings are shared.

How much does this cost to run?

The software is free. Model usage is the cost: subscription logins (like Nous Portal) bundle many models behind one login; API keys bill per token; local models cost electricity. A light personal setup typically stays modest; heavy automation scales with usage.

Can I run it fully offline?

Yes, with a local model through an OpenAI-compatible server such as Ollama or llama.cpp — the agent runs on your machine either way. Web search, hosted models and some tools obviously need connectivity.

Where are my sessions and skills stored?

Everything lives under ~/.hermes/ — sessions in state.db plus transcripts, skills in skills/, secrets in .env, settings in config.yaml. Back up that folder and you've backed up your agent.

Windows says 'hermes' is not recognized after install.

Close and reopen PowerShell so PATH changes load, then retry. If it persists, re-run the installer, which prints the exact location of the hermes command.