Hermes Agent
Hermes Agent on Mac: install, Apple Silicon and Homebrew
Updated 20 November 2026
Hermes Agent runs on macOS, and this page compares three installation routes: the desktop package, the install script, and a Homebrew formula that exists but is not the route the Hermes docs support. It also sorts out which Macs are covered, what each route gives you, where the files go and how to keep the gateway running.
Facts come from the Hermes Agent 0.23.3 documentation (installation, platform support, quickstart and CLI reference) and the Homebrew formula record for hermes-agent, all read on 20 November 2026.
Which Macs are supported
The platform support page lists macOS (Apple Silicon) as Tier 1, the group it says it strives never to break and puts first when something regresses. Its install methods are Hermes Desktop and install.sh.
Intel Macs are where the documents need careful reading, because they do not say exactly the same thing in every place:
- The installation guide says the macOS installer is Apple Silicon only, and that macOS on x86 (Intel) processors is “not a supported platform”.
- The platform support page’s unsupported list names 32-bit x86 macOS and Intel x86_64 macOS desktop bundles, none of which are built. It adds that the
Hermes-Setup.dmgbootstrap installer is Apple Silicon only and, on an Intel Mac, reports that it is not supported on that Mac. - The same page also says Intel Macs can install the CLI and run
hermes desktop. Because that is the more specific statement about what an Intel Mac can do, treat it as “possible, but outside the Tier 1 promise”, not as a tested, supported setup.
If you have an Intel Mac and want something you can rely on, the Hermes documents do not give you that promise. Memory, disk and the other basics are covered on our Hermes Agent system requirements page.
The ways to install on a Mac
The quickstart recommends the Hermes Desktop installer on macOS or Windows. The command-line route is the install script. Homebrew is a third option that the docs explicitly do not support.
| Route | How | What the sources say |
|---|---|---|
| Desktop package | Download from the Hermes website, open the DMG, copy Hermes.app to Applications | Apple Silicon only. Bundles the agent, Python, supported dependencies and prebuilt interfaces; the base runtime is not built on first launch. |
| Install script | curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash | Listed for Linux, macOS and WSL2. Gives the command line; run hermes desktop afterwards if you want the desktop app too. |
| Homebrew | brew install hermes-agent | Listed as unsupported in the Hermes docs. The formula was at 0.22.4 when read (see below). |
For the general install on every system, see how to install Hermes Agent.
The desktop package and the install script
Desktop package. In the macOS download, the DMG is what you open, and the ZIP artifact carries the signed app that the automatic updater uses. The installation guide describes bundled packages as containing everything needed for the base runtime, though provider access and optional integrations can still need network access. A Hermes-Setup bootstrap installer is a different thing: it downloads a source installation and builds the desktop app. The desktop app itself has its own page: Hermes Agent desktop app.
Install script. The scripts clone the source, set up uv and hand dependency preparation to Hermes’s package manager, which provides pinned Python, Node.js, npm, pnpm, ripgrep and FFmpeg. It also installs browser and computer-use tools by default: a pinned Chromium that Hermes launches for local browsing, and cua-driver, the computer-use driver. If a download fails, the install still completes and prints the command to retry. A new install lands on the latest stable release, the channel hermes update follows afterwards; --channel main installs the tip of main instead.
After the script finishes, reload your shell and start chatting. For zsh, use:
source ~/.zshrc
hermesPrerequisites for the script on a Unix-like system are Git, curl, tar and SHA-256 utilities. The script always downloads its own verified uv, so a uv on your path is not used. Later setup is done with hermes model, hermes tools, hermes gateway setup and hermes setup.
Homebrew: what exists and what to know
Homebrew’s own record (formulae.brew.sh, read 20 November 2026) shows a core formula called hermes-agent, described as a self-improving AI agent that creates skills from experience, with an MIT licence. So brew install hermes-agent is the command the formula name implies.
- Version. The stable version on that date was 0.22.4. The documentation this page follows describes Hermes 0.23.3, so the formula version was older than the documentation version.
- Which Macs. The bottles listed for macOS are all Apple Silicon:
arm64_tahoe,arm64_sequoiaandarm64_golden_gate. The record shows no Intel macOS bottle, so we cannot say the formula works on an Intel Mac. It also lists Linux bottles. - Dependencies. It pulls in Python 3.14, Node, ripgrep and others; build dependencies are Rust and pkgconf.
- Caveat. Voice and text-to-speech audio conversion optionally uses ffmpeg, which you install separately with
brew install ffmpeg. - Official stance. The Hermes platform support page lists installs via
brewunder unsupported distribution methods, and says fixes for them are not accepted. The installation guide does not mention Homebrew as an install route.
In short: Homebrew gives you a package, but not the route Nous Research backs, and it ran behind the docs on the day we read it. Using it is your call; if something breaks, the documented advice is to move to the install script or the desktop package.
Where Hermes keeps its files on a Mac
The installation guide gives this layout for the POSIX source script, which is what a Mac uses:
| What | Location |
|---|---|
| Code | ~/.hermes/hermes-agent/ |
| Command | ~/.local/bin/hermes (a wrapper) |
| User data | ~/.hermes/ |
The HERMES_HOME setting selects where user data lives, and the script’s --dir option picks the source checkout independently. Install output is written to logs/install.log under the Hermes data directory.
For the desktop bundle, the guide says the code sits inside the installed app package and the data goes to the “platform default Hermes data directory”. It does not name the macOS path, so we do not either; hermes doctor reports the installation provenance, and the guide says to leave the data root alone when repairing an application install. Hermes preserves symlinks in its user data directory. If a link target is missing, inaccessible or not a directory, initialization stops with a storage error instead of creating the target. This checks directory availability; an existing directory does not prove that the intended volume is mounted.
Updates follow the owner of the install: source checkouts use hermes update, while desktop bundles keep their own updater. See updating Hermes Agent, and uninstalling Hermes Agent to remove it.
Keeping the gateway running in the background
The gateway is the process that connects Hermes to chat apps. On a Mac, the CLI reference says hermes gateway install installs it as a launchd background service (a systemd service on Linux). Then:
hermes gateway setup
hermes gateway install
hermes gateway start
hermes gateway statusRun hermes gateway setup first to connect your messaging platforms. To run the gateway in the foreground in a terminal instead, use hermes gateway run.
If you wrap the gateway in your own launchd job, the reference describes --external-supervisor on run. In that mode a restart exits with status 75, so your launchd job needs KeepAlive set to relaunch it after an unsuccessful exit; without that policy a requested restart leaves the gateway stopped.
See also Hermes Agent on Telegram for a first chat app.
Mac-specific features and snags
Computer use. The cua-driver backend behind the computer-use toolset works on macOS, Windows and Linux. On a Mac it needs two permissions, Accessibility and Screen Recording. The CLI reference gives these commands:
hermes computer-use install
hermes computer-use status
hermes computer-use doctor
hermes computer-use permissions status
hermes computer-use permissions grantpermissions status reports the two grants and permissions grant asks macOS to give them to Cua Driver. To leave the driver out at install time, pass --skip-computer-use to the script; hermes pm install cua-driver installs it later and undoes that choice.
Function keys in the terminal interface. The docs note that on macOS F6 and F7 mean the physical function keys, so hold Fn (the globe key on newer keyboards) while pressing them, or turn on “Use F1, F2, etc. keys as standard function keys” in System Settings, Keyboard, Keyboard Shortcuts, Function Keys. The terminal fallbacks are Ctrl+T for F6 and Ctrl+R for F7.
Command not found. If hermes is not found after installing, reload your shell or check your PATH (the guide’s fix). If a key is missing, run hermes model; hermes doctor reports what else is missing.
Running a model on the Mac itself is a separate topic; see Hermes Agent with Ollama.
Hermes Agent on a Mac, without installing it: ReadyHermes
A ReadyHermes assistant runs on our servers, so nothing is installed on your Mac and it keeps working when the computer is asleep or off. You use it from a browser and from the chat apps you connect (Telegram, WhatsApp, Discord, WeChat or Lark). We do not offer a Mac-specific ReadyHermes app, and there is no native iPhone or Android app either.
If you already use the Hermes Desktop app, it can talk to your hosted agent: in your workspace, open Channels, then Hermes Desktop, and copy the remote URL and sign-in into the app’s Remote gateway setting. Plans start at US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month, and there is a one-hour free trial. For the trade-offs, see self-hosting vs managed hosting.
Questions
Does Hermes Agent run on Apple Silicon Macs?
Yes. The platform support page lists macOS on Apple Silicon as Tier 1, with Hermes Desktop and install.sh as the install methods. The macOS desktop installer is Apple Silicon only.
Does Hermes Agent work on an Intel Mac?
Not as a supported setup. The installation guide says Intel macOS is not a supported platform and no Intel desktop bundle is built. The platform support page adds that Intel Macs can install the CLI and run hermes desktop, but that sits outside the Tier 1 promise.
Can I install Hermes Agent with Homebrew?
A formula called hermes-agent exists, so brew install hermes-agent is the implied command. On 20 November 2026 it was at 0.22.4 against 0.23.3 in the docs, and its macOS bottles were Apple Silicon only. The Hermes docs list brew installs as unsupported.
How do I keep the Hermes gateway running on a Mac?
Run hermes gateway setup, then hermes gateway install, which installs a launchd background service on macOS. Start it with hermes gateway start and check it with hermes gateway status.
Does Hermes Agent support computer use on macOS?
Yes, through the cua-driver backend, installed by default by the install script. On a Mac it needs Accessibility and Screen Recording permissions; hermes computer-use permissions status reports them and permissions grant asks macOS to grant them.