How much disk space does Hermes use on a Mac?

Roughly 200 MB for a fresh install, plus another 100–500 MB over time for sessions, skills, and memory under ~/.hermes/.

handbook · install · macos

How to Install Hermes Agent on a Mac

Q: Does Hermes work on Apple Silicon (M1, M2, M3, M4)?

Yes — macOS on Apple Silicon is a Tier 1 platform. The installer pulls native arm64 binaries; no Rosetta required.

Q: Does Hermes Agent work on Intel Macs?

No — macOS on Intel (x86) processors is explicitly listed as unsupported in the official platform matrix. It may be broken now and may break more; compatibility code can be removed at any point. Use a Linux machine, a VPS, or the Docker image on other hardware instead.

Q: Can I install Hermes with Homebrew?

No — brew install hermes-agent is an officially unsupported path, as are pip and uv tool installs. Use the Hermes Desktop installer or the official curl one-liner.

Q: Should I use the Desktop installer or the curl install on a Mac?

The Desktop installer is the recommended easy path and gives you the app plus the CLI in one shot; the curl one-liner is for terminal-only installs. They share the same agent core, config, and data — and running hermes desktop later upgrades a CLI install to the app.

Q: Is a Mac mini a good always-on Hermes host?

An Apple Silicon Mac mini works well as an always-on host — it's a Tier 1 platform. For headless server-style setups, compare the Docker/VPS route, which adds supervised auto-restart.

Desktop installer or one curl command — Apple Silicon only, and honest about it. A platform page of the install guide, cross-checked against the official docs.

By Kevin Simback · Hermes Atlas maintainer · Updated 2026-10-12 · ~5 min read

TL;DR

Two supported paths, both Tier 1 on Apple Silicon (M1–M4). The official install page recommends the Hermes Desktop installer — download, run, and you get the desktop app and the CLI sharing one config. Terminal-only? One command:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.zshrc     # macOS default shell since Catalina
hermes              # start chatting

This guide covers Hermes Agent v0.21.5. On other platforms? See Windows, Linux, Raspberry Pi, or VPS.

What's supported on a Mac — and what isn't

Setup	Status	Notes
Apple Silicon (M1–M4) + Desktop installer or `install.sh`	Tier 1	"We strive to never break installations and updates for these" — first-priority fixes
Intel (x86) Macs	Unsupported	Explicitly listed as unsupported; may be broken now, compat code can be removed any time
`brew install hermes-agent`	Unsupported	Same list — migrate to the Desktop installer or `install.sh`
`pip` / `uv tool install`	Unsupported	PyPI installs are not a supported distribution method

Source: the official platform support matrix. If you're on an Intel Mac, the practical alternatives are Hermes on a Linux box or VPS you connect to remotely, or the Docker image (Tier 1 on x86_64) on other hardware.

Prerequisites

Just Git (git --version — macOS offers the Xcode Command Line Tools automatically if it's missing). Per the official docs, the installer handles everything else itself: uv, Python 3.11 (no sudo), Node.js 26 (an existing Node 22.22+/24.11+/26+ is used as-is), ripgrep, and ffmpeg. You do not need to brew-install any of those first.

Install and verify

Path 1 — Desktop installer (recommended): download Hermes Desktop, run it, and it provisions the CLI runtime into ~/.hermes — the same layout a CLI install uses, which is why the app and terminal are interchangeable afterwards. We cover the app itself in the Hermes Desktop guide.

Path 2 — CLI-only: the curl command from the TL;DR. Code lands in ~/.hermes/hermes-agent/, the launcher at ~/.local/bin/hermes, your data (config, keys, sessions, skills, memory) in ~/.hermes/. Then verify:

hermes version      # prints v0.21.5 (or newer)
hermes doctor       # health check — every line should be green

First run: hermes starts the provider wizard. The fastest path is hermes setup --portal — one Nous Portal login covers 300+ models plus the Tool Gateway. All four provider paths (Portal, your own API key, local Ollama, skip-for-now) are walked through in first run and model provider. Moving from another machine? hermes import restores a full backup instead of re-configuring.

Installed CLI-only and want the app later? Run hermes desktop — it installs and launches Hermes Desktop against your existing config.

If something breaks

The two Mac-specific failures we see: ffmpeg/ripgrep resolution on Apple Silicon when Homebrew's /opt/homebrew/bin isn't in your shell env (add eval "$(/opt/homebrew/bin/brew shellenv)" to ~/.zshrc), and hermes: command not found right after install (reload with source ~/.zshrc or open a new terminal). Everything else — API-key errors, npm failures, hung downloads — is in the shared troubleshooting tree, and hermes doctor diagnoses most of it.

FAQ

Does Hermes work on Apple Silicon (M1, M2, M3, M4)?

Yes — macOS on Apple Silicon is Tier 1. The installer pulls native arm64 binaries; no Rosetta required.

Does Hermes Agent work on Intel Macs?

No — Intel Macs are explicitly unsupported. Use a Linux machine, a VPS, or Docker on other hardware instead.

Can I install Hermes with Homebrew?

No — brew install hermes-agent is an officially unsupported path, as are pip/uv tool installs. Use the Desktop installer or the curl one-liner.

Should I use the Desktop installer or the curl install?

Desktop installer if you want the app (it's the recommended easy path); curl if you're terminal-only. Same agent core, same config — and hermes desktop upgrades a CLI install any time.

Is a Mac mini a good always-on Hermes host?

An Apple Silicon Mac mini works well — Tier 1, quiet, and popular for exactly this. For headless server-style uptime, compare the Docker/VPS route.

How much disk space does Hermes use?

Roughly 200 MB fresh, plus 100–500 MB over time for sessions, skills, and memory.

Next: verify the install, pick a model provider, then the Skills Hub. Deciding between the app and the terminal? Every mode compared.

Maintained by Kevin Simback · Part of The Hermes Handbook · Facts sourced from the official Hermes Agent docs · if this was useful, drop a ★ on the atlas repo →