NousResearch/hermes-agent installation guide

Install Hermes Agent on macOS Tahoe (Apple silicon)

What you are installing

Hermes Agent is an MIT-licensed, Python-based AI agent from Nous Research. It has its own terminal interface, model-provider setup, tools, memory, skills, messaging gateway, and optional native desktop application. The repository says the same agent, configuration, sessions, memory, and skills are shared across its CLI, gateway, and Desktop surfaces.

Relationship to Claude Code

**Classification: standalone application that runs alongside Claude Code.** Hermes is best treated as an alternative or companion agent, not a Claude Code extension. The supplied first-party files document a separate `hermes` CLI, an optional Hermes Desktop app, an MCP host, plugins, skills, tools, and its own agent runtime. They do **not** document installing this repository as a Claude Code plugin, hook, subagent, or MCP server for Claude Code. Although the metadata mentions Claude and Claude Code and Hermes supports the agentskills.io standard, that alone does not establish native Claude Code integration.

In practical terms, installing Hermes does not replace or modify Claude Code according to the supplied evidence. You launch Hermes separately with `hermes` or `hermes --tui`.

Before you begin

This walkthrough is for a normal local installation on a Mac with Apple silicon running macOS Tahoe. The repository documents support for macOS and says its installer handles platform-specific configuration, but the supplied files do not provide a Tahoe-specific or Apple-silicon-specific compatibility matrix. They also provide no separate Apple-silicon command. Use the documented macOS installer below rather than inventing architecture flags.

You will need:

• An internet connection.
• Permission to install files under your user account.
• Access to the macOS **Terminal** application.
• A model provider. Hermes supports Nous Portal, OpenRouter, OpenAI, custom endpoints, and other providers. Provider accounts, API usage, or a Nous Portal subscription may cost money.

The official quick-install command downloads a shell script and immediately runs it. That is convenient, but it means you are trusting the current script served by the project website. The supplied repository files do not document a checksum, signature-verification command, or offline installer-verification procedure for macOS.

Step 1: Open Terminal

On your Mac, open **Terminal** from Applications → Utilities, or find it with Spotlight. Commands in this guide go into Terminal. Copy only the text inside each code block, paste it into Terminal, and press Return.

You do not need to clone the GitHub repository for an ordinary installation. The repository explicitly recommends its standard installer, which creates and manages the expected Hermes layout.

Step 2: Run the documented macOS installer

Paste this one command:

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

Wait for it to finish. Do not close Terminal while installation is in progress. The project describes this as the quick-install path for Linux, macOS, WSL2, and Termux. Its managed installation normally lives under `~/.hermes`, and the source checkout used by the managed installation is usually `~/.hermes/hermes-agent`.

Do not use the contributor-only editable-install commands unless you intend to develop Hermes itself. Those commands install development dependencies and run the project test suite; they are not needed for normal use.

Step 3: Reload your shell

The README says to reload either Bash or Zsh after installation. On a typical modern macOS setup, use the documented Zsh form:

source ~/.zshrc

If you deliberately use Bash instead, the repository supplies this alternative:

source ~/.bashrc

Run only the one matching your shell. Reloading allows the current Terminal window to see the newly installed `hermes` command. Opening a new Terminal window is also a reasonable interface action, but no extra command is needed for that.

Step 4: Run the setup wizard

Start the complete interactive setup process:

hermes setup

Follow the prompts shown in Terminal. The README describes this as the full setup wizard that configures everything at once. Choose a provider and model when asked. The supplied files do not document exact wizard screens, required key names for every provider, or a universal free model, so follow the current prompts rather than pasting guessed environment-variable commands.

Treat API keys and access tokens like passwords. Do not paste them into chats, source files, screenshots, or public issue reports. Before enabling powerful tools or unattended automation, review the project’s security documentation, especially command approval, messaging pairing, and container isolation.

Optional: use Nous Portal

If you prefer the project’s OAuth-based Nous Portal route, the README provides a dedicated setup command:

hermes setup --portal

The repository says this signs you in with OAuth, selects Nous as the provider, and enables its Tool Gateway. Nous Portal is optional and offered as a subscription covering model access and services such as web search, image generation, text-to-speech, and a cloud browser. You can inspect the resulting Portal connection with:

hermes portal info

Use either the general setup wizard or the Portal route according to your provider choice; you do not need to run both just to complete installation.

Step 5: Check the installation

Run the project’s diagnostic command:

hermes doctor

This is the documented command for diagnosing issues. Read any messages it prints and address missing authentication or configuration through the setup wizard. The supplied files do not include source-supported macOS commands for manually repairing individual installer dependencies, so avoid guessed Homebrew, pip, npm, or system-Python fixes.

You can review or change the selected model with:

hermes model

You can also configure which agent tools are enabled:

hermes tools

Tool access matters because Hermes can work with files, terminal commands, networks, and external services. Start with only the capabilities you understand and need. Hermes includes approval flows, but approval and isolation settings still deserve careful review before allowing broad access.

Step 6: Start Hermes

Launch the interactive terminal experience:

hermes

You should enter the Hermes conversation interface. Type a message and submit it as directed by the interface. The repository describes a terminal UI with multiline editing, conversation history, streaming tool output, and slash commands.

The explicitly documented TUI form is also available:

hermes --tui

Inside the TUI, `Ctrl+C` interrupts active work; if no work or draft is pending, it exits. `Ctrl+D` also exits. Review requests to run terminal commands or access sensitive resources before approving them.

Optional: install and launch Hermes Desktop

Hermes Desktop is the project’s native graphical application. It is not required for the CLI. Once the Hermes CLI works, use the repository’s recommended Desktop command:

hermes desktop

The project says this builds and launches the GUI against your existing installation, sharing the same configuration, keys, sessions, and skills. On first launch, Desktop can connect to an existing Hermes gateway or use a local Hermes runtime. The repository also points to its website for prebuilt installers, but the supplied files do not provide a copy-paste download or verification command, so this guide does not invent one.

Remember that a native window does not reduce the agent’s underlying permissions. Local tool and file operations still run through the Hermes backend. In remote mode, the remote gateway host—not the Mac displaying the UI—is the execution boundary.

Optional: configure messaging later

Hermes can connect to services such as Telegram, Discord, Slack, WhatsApp, and Signal. This is not necessary for a first local conversation. When you are ready, begin the documented interactive gateway setup:

hermes gateway setup

Then start it with:

hermes gateway start

A continuously running gateway can receive messages and perform work, so configure allowed users, credentials, working directories, and security controls carefully. Do not expose it publicly without reading the project’s messaging and security documentation.

Updating Hermes

The documented update command is:

hermes update

Run it when you intentionally want the latest project version. Updating can change code and dependencies, so avoid doing it in the middle of important work. Hermes Desktop also reportedly checks for updates in the background and offers a one-click update.

If something goes wrong

First, run:

hermes doctor

If the command is not found immediately after installation, reload the applicable shell configuration again:

source ~/.zshrc

Then retry:

hermes

For unresolved problems, use the repository’s public issue tracker at `https://github.com/NousResearch/hermes-agent/issues` or its documentation at `https://hermes-agent.nousresearch.com/docs/`. Do not post API keys, tokens, private prompts, configuration secrets, or personal conversation data.

The supplied first-party files do not document a standard uninstall command for macOS. Therefore, this guide does not recommend deleting guessed directories or running an undocumented cleanup script. Consult the current official documentation or ask the maintainers for the supported removal procedure.