Beginner guide · Hermes Agent

How to install Hermes Agent (Mac, Windows, Linux)

Short answer: on a Mac with Apple silicon or a Windows PC, download the Hermes Desktop app from the Hermes website. On Linux (or if you want command line only), run one install command, then hermes setup to connect an AI model. Test one plain chat before you connect Telegram, email or anything else, and keep approvals on.

Updated · By BotsDoThat

Every command here is from Nous Research's official Hermes docs, linked inline. Hermes changes often, so check the linked page if a step looks different.

Before you start

  • A computer that stays on if you want it to answer you all day: your own Mac, Windows PC, Linux machine or a server. Prefer not to run one? Hermes Cloud is a hosted, always-on Hermes included with paid Nous Portal plans (Hermes).
  • Mac users: the macOS installer is Apple silicon only; Intel Macs are not a supported platform (install docs).
  • An AI model. Options include a Nous Portal subscription, your ChatGPT or Codex subscription, an Anthropic, OpenRouter or Google AI Studio key, or a local model. The model needs at least 64,000 tokens of context; for a local model, set its context size to 64K (quickstart).
  • Ten quiet minutes and one test job. Don't connect your real inbox on day one.

Step 1: Install Hermes Agent

Easiest: the desktop app (Mac or Windows)

The quickstart calls the Hermes Desktop installer the recommended route on macOS and Windows (quickstart). Download it from the Hermes website. On Windows, open the .appinstaller file with Windows App Installer. On a Mac, open the DMG and copy Hermes.app to Applications. The bundle already contains the agent and what it needs to run (install docs).

Command line: Linux, macOS or WSL2

Terminal (Linux, macOS, WSL2)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Command line: Windows (PowerShell)

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

Then reload your terminal (source ~/.bashrc or source ~/.zshrc). The installer also adds a browser and a computer-use driver by default; add --skip-browser or --skip-computer-use (Windows: -SkipBrowser, -SkipComputerUse) to leave them out. Want the desktop app later? Run hermes desktop (install docs).

Android phones (aarch64) use the Termux package (pkg install hermes-agent), not these scripts. Docker installs update by pulling the image, for example docker pull nousresearch/hermes-agent:latest (install docs, updating).

Running a command that pipes a web script into your shell means trusting that site. Copy it only from the official docs page.

Step 2: Connect an AI model

Run hermes setup. On a fresh install it offers three modes (quickstart):

  • Quick Setup (Nous Portal): sign in, no API keys to manage; billed to a Nous Portal subscription. Shortcut: hermes setup --portal.
  • Full Setup: pick each provider and tool yourself and bring your own keys, or sign in with a ChatGPT/Codex plan.
  • Blank Slate: almost everything starts off (only the model, file and terminal tools). The careful choice if you want to turn on tools one at a time.

Already know your provider? hermes model does just that step. Secrets go to ~/.hermes/.env and normal settings to ~/.hermes/config.yaml (quickstart). Coming from OpenClaw? hermes setup offers to import your setup when it finds one; see also Migrate from OpenClaw. Worried about the bill? See switch Hermes to a cheaper model and what an AI agent costs per month.

Step 3: Run one test chat

Start hermes (or hermes --tui for the newer screen). The docs' advice: if Hermes can't finish a normal chat, don't add features yet (quickstart). It's working when:

  • the banner shows the model you picked,
  • it replies without an error and keeps going for more than one turn,
  • hermes -c brings you back to the same conversation.

Step 4: Make it safe before you connect anything

  1. Keep approvals on. The default “smart” mode lets a helper model approve low-risk commands, deny dangerous ones and ask you when unsure; “manual” always asks. Don't set approvals to off or start with --yolo, which skip the prompts (Hermes security).
  2. Use the sandbox. hermes config set terminal.backend docker runs the agent's commands in a container instead of on your computer (quickstart).
  3. Add chat apps last. hermes gateway setup connects Telegram, Discord, Slack, WhatsApp, Signal or email. Unknown people are denied unless you allowlist them or approve a pairing code with hermes pairing approve; never set GATEWAY_ALLOW_ALL_USERS=true (Hermes security).
  4. Protect your keys: chmod 600 ~/.hermes/.env, and set a spend limit at your AI provider: set spend limits and usage alerts on your AI accounts.
  5. Start with read-only jobs. A summary or a watcher before anything that sends, buys or deletes. More: is it safe to give an AI agent your email? and how to keep an AI agent from deleting your files.

If the install fails

What you seeWhat to do
hermes: command not foundReload your shell (source ~/.bashrc) or check PATH
API key not setRun hermes model to set up a provider
Opens, but replies are empty or brokenRun hermes model again and check provider, model and sign-in
Bot connected, but nobody can message itRe-run hermes gateway setup; check hermes gateway status and your allowlist
Anything elsehermes doctor, then hermes model, then hermes setup

From install docs and quickstart. The installer writes a log to logs/install.log in the Hermes data folder.

Updating and uninstalling

Command-line installs update with hermes update; the desktop app updates from its own Update control. To remove it, run hermes uninstall --dry-run first to see what would go, and hermes backup if you might come back (updating docs).

What to hand it first

Any of our 12 blueprints works as instructions for Hermes. Good first ones: Morning Inbox Briefing and Web Page Watcher. Write your own with the 6-part instructions template. Still choosing? OpenClaw vs Hermes Agent or OpenClaw alternatives for beginners.

Questions

How do I install Hermes Agent?

On a Mac with Apple silicon or a Windows PC, the docs recommend the Hermes Desktop installer from the Hermes website. For a command-line install, run curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash on Linux, macOS or WSL2, or iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell on Windows. Then run hermes setup to connect a model.

How do I install Hermes Agent on Windows?

Either download the Windows desktop package from the Hermes website and open it with Windows App Installer, or run iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell for a command-line install. WSL2 also works with the Linux installer.

Does Hermes Agent work on an Intel Mac?

Not officially. The installation docs say the macOS installer is Apple silicon only and that macOS on Intel processors is not a supported platform.

Is Hermes Agent safe?

It has real safety controls, but the defaults are not a lock. By default it asks (or has a helper model judge) before dangerous commands, scheduled jobs deny dangerous commands, and unknown people who message your bot are denied unless you pair or allowlist them. It still runs commands on your own computer unless you switch on the Docker sandbox, and turning approvals off or using --yolo removes the prompts. Give it only the accounts it needs.

Hermes Agent install failed. What should I do?

Run hermes doctor first; it reports what's missing. If the shell says hermes: command not found, reload it (source ~/.bashrc or ~/.zshrc). If it says API key not set, run hermes model. The installer writes a log to logs/install.log in the Hermes data folder, and a failed step prints its last lines.

Is Hermes Agent free?

The software is free and open source under the MIT license. You pay for the AI model you connect (or use a plan you already have, like a ChatGPT or Codex subscription), and Nous Portal is an optional paid subscription.

How do I update or uninstall Hermes Agent?

For a command-line install, run hermes update; the desktop app has its own Update control. To remove it, run hermes uninstall --dry-run first to see what would go, and hermes backup if you might want your setup later.

Sources

BotsDoThat Weekly

Get the free Starter Pack: 7 AI agents you can put on a schedule

Join the BotsDoThat Weekly and we'll send you 7 ready-to-paste setups for ChatGPT, Claude, OpenClaw and Hermes Agent, plus a bonus for power users. Each one asks you before it sends, buys or deletes anything.

We'll email you a confirm button. Click it to confirm and get your Starter Pack. Unsubscribe any time. Privacy

Know someone who'd like this? Forward it, or send them to botsdothat.com/newsletter