Hermes Agent Zone

Guides

How to install Hermes Agent on macOS

Published August 5, 2026 · Verified on v0.19.0

macOS is the easiest platform to get Hermes running on and the worst platform to run it on long-term. Both halves of that are worth knowing before you start. If you want a graphical app, start with the desktop installer; if you want terminal access or a scriptable setup, use the command-line path below.

Option A — desktop installer

Download the current macOS build from the official Hermes Agent website. This is the fastest route for most Mac users and does not require you to begin in Terminal.

Option B — command-line installer

Step 1 — make sure you have Git

Git is the only real prerequisite. macOS does not ship it until you ask:

git --version

If that prompts you to install developer tools, accept it — or trigger it yourself:

xcode-select --install

That is a few hundred megabytes of Apple command line tools. If you already have Git through Homebrew, you are set and can skip this.

Step 2 — install

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Without sudo. Hermes installs into the home directory of whoever runs it, and running as root puts it somewhere your normal account cannot reach.

To read the script first — a sensible habit for anything piped into a shell:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o hermes-install.sh
less hermes-install.sh
bash hermes-install.sh

The installer pulls uv, Python 3.11, Node.js v22, ripgrep and ffmpeg. Code goes to ~/.hermes/hermes-agent/, and the hermes launcher is symlinked into ~/.local/bin/.

This works the same on Apple Silicon and Intel. The runtimes are fetched as native builds, so there is no Rosetta step and no conflict with whatever Python your system or Homebrew already has.

Step 3 — reload zsh, not bash

source ~/.zshrc

macOS has defaulted to zsh since Catalina. Guides written for Linux say source ~/.bashrc, which on a Mac silently does nothing — and then hermes appears not to exist. If you are unsure which shell you are in:

echo $SHELL

Still not found after reloading? ~/.local/bin is missing from your PATH — here is the one-line fix.

Step 4 — verify

hermes doctor

Do this before configuring anything. It checks dependencies, config location and provider setup together.

Step 5 — pick a model

hermes model     # choose your provider
hermes           # start chatting

An HTTP 400 on the first message means the configured model identifier does not match your provider’s catalogue — here is how to prove it.

Launching Desktop from a CLI installation

If you chose the CLI installer, you can launch the free MIT-licensed GUI with:

hermes desktop

The laptop problem

Hermes keeps persistent memory and can run chat gateways for Telegram, Discord, Slack and others. That only means something if the machine is awake.

A closed MacBook is not answering messages. caffeinate can hold sleep off while plugged in, but a laptop you carry around is structurally the wrong host for an always-on agent — you will close the lid, and the agent will go dark.

The realistic split:

Running both is normal. They are separate installs with separate memory, so decide early which one is the agent that matters.

Upgrading

Hermes ships releases most weeks. Check the changelog for breaking changes first, then re-run hermes doctor afterwards.

FAQ

Does Hermes Agent work on Apple Silicon?

Yes, natively on M-series Macs as well as Intel. The installer brings its own Python 3.11 and Node.js v22 builds, so you do not need Rosetta and you do not need to match a system Python.

Why does source ~/.bashrc do nothing on my Mac?

macOS has used zsh as the default shell since Catalina. Edit and source ~/.zshrc instead. This single detail accounts for a large share of "installed but command not found" reports from Mac users.

Will Hermes keep running when I close my laptop?

No. A sleeping Mac is not answering Telegram messages. A laptop is fine for interactive use, but for an always-on agent you want a small server instead.

Related