Hermes Agent GitHub: Installation and Configuration

The Hermes Agent GitHub repository is more than a download link. Every install on a Mac is a git checkout of it. This guide explains how the repository is laid out, how to install from source, how releases and branches work, and how to update or contribute without breaking a working setup.

The repository at a glance

The official repository is github.com/NousResearch/hermes-agent. It is MIT-licensed and maintained by Nous Research. Hatmac is not affiliated with the project. The parts you will meet most often:

Path	What it is
---	---
run_agent.py, agent/	The agent loop, prompt building, context compression
cli.py, hermes_cli/	The hermes command, setup wizard, config handling, doctor
tools/	Self-registering tools and terminal backends
gateway/	The messaging gateway and platform adapters
skills/, optional-skills/	Bundled skills and official optional ones
scripts/install.sh	The Linux and macOS installer
cli-config.yaml.example	Example configuration, copied to ~/.hermes/config.yaml
.env.example	Example secrets file
website/docs/	The source of the official documentation
CONTRIBUTING.md, AGENTS.md	Contributor guide and notes for AI coding assistants

Two ways to install from GitHub

There are two supported paths, and they suit different people.

1. Managed checkout (for users). The official installer clones the repository to ~/.hermes/hermes-agent, prepares the dependencies and puts a hermes wrapper at ~/.local/bin/hermes. You update it with hermes update. This is what our Mac mini install guide covers.
2. Developer checkout (for contributors and tinkerers). You clone the repository yourself, anywhere you like, and activate its environment in your shell. This is the path the rest of this guide focuses on.

Two shortcuts are not supported. The project's platform page lists installs via PyPI (pip install or uv tool install) and via Homebrew (brew install hermes-agent) as unsupported. Use one of the two paths above.

Prerequisites for a source checkout on macOS

The contributor guide lists four requirements:

• Git with the git-lfs extension. Git comes with Apple's Command Line Tools (xcode-select --install). git-lfs is available from Homebrew.
• Python 3.14. The project pins >=3.14,<3.15. You do not install it yourself, because the project's package manager (PM) provides the pinned interpreter.
• Node.js and pnpm, also provided at pinned versions when you activate.
• A native compiler for any dependency without a prebuilt wheel. The Command Line Tools cover this on macOS.

xcode-select --install
brew install git-lfs
git lfs install

Clone and activate the environment

Clone the repository, then choose a separate data home so experiments never touch a production ~/.hermes:

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
bash
export HERMES_HOME="$HOME/hermes-dev-data"
export HERMES_RUNTIME_DIR="$HERMES_HOME/tools"
source ./activate
hermes --version

Note the bash line. The activate script uses Bash syntax, and the docs warn against assuming that zsh, the macOS default shell, behaves the same. fish users have activate.fish instead.

Activation fetches the pinned Python and tools on first use, syncs the dependencies, and defines hermes as a shell function that runs this checkout. That function only works inside the worktree and hides any installed hermes while you are there. deactivate restores your shell. To run a single command without activating, use scripts/run-in-hermes-env.

Do not change the environment with raw pip or uv commands. uv is an internal detail of the package manager, and the docs say plainly that a PM-built environment should not be modified that way. Configure the development home with hermes setup, rather than copying production keys into the checkout.

Branches, tags and release channels

• **main** receives every merged change.
• Release tags mark stable versions. See the repository's Releases and tags pages for the current one.
• The stable channel is the default for new installs. hermes update moves a managed checkout to the latest release tag.

You can choose differently at install time or later:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --channel main
hermes update --set-channel main      # follow every commit on main
hermes update --set-channel stable    # back to releases only
hermes update --check                 # see what an update would do
hermes update --branch some-branch    # update against another branch

For a Mac that runs an agent other people rely on, stay on stable. Use main on a development machine.

Configuration files reference

Whichever way you install, user configuration lives outside the checkout, in HERMES_HOME:

File	Created from	Purpose
---	---	---
config.yaml	cli-config.yaml.example	Model, toolsets, terminal backend, approvals, memory, gateway
.env	.env.example	API keys, bot tokens and other secrets
auth.json	OAuth logins	Nous Portal and other OAuth credentials
SOUL.md	Setup	The agent's identity
memories/, skills/	Runtime	Persistent memory and skills
state.db	Runtime	SQLite session database with full-text search
cron/, logs/	Runtime	Scheduled jobs and log files

Read cli-config.yaml.example in the repository when you want to see an option with its comments. After an update adds new options, hermes config check lists what is missing and hermes config migrate adds it interactively. For what each setting does on a Mac, see our complete Hermes setup guide.

Updating: hermes update or git pull

**On a managed checkout, use hermes update, not git pull.** It does more than pull:

• takes a snapshot of state files such as config.yaml, .env, auth.json and cron jobs;
• applies the stable tag or the selected branch and updates submodules;
• compiles the files every hermes start imports, and rolls the checkout back if one fails to parse;
• syncs dependencies and restarts gateways that were running.

If you keep local patches, do not commit them on main. When main has diverged, the update resets it to origin/main and saves your old commits under a refs/hermes-update-backups/ ref. Keep patches on your own branch and set updates.parked_branch_strategy: update_in_place, and the update merges upstream into that branch instead.

On a developer checkout, plain git is fine. Pull, then reactivate so the environment syncs with the updated lock file:

git pull
source ./activate

Contributing back

The contributor guide asks you to search existing issues and pull requests first, and to decide whether a change belongs in a skill (instructions plus scripts) or a tool (Python code with a schema). Before opening a pull request, run the same checks CI runs:

scripts/run_tests.sh
scripts/run_tests.sh tests/agent/ -v
python scripts/check

The test runner clears credentials and isolates HERMES_HOME, so tests never touch your real setup. If you change scripts/install.sh, the guide asks for the matching change in scripts/install.ps1.

Troubleshooting

Symptom	Likely fix
---	---
hermes: command not found after install	source ~/.zshrc, or add ~/.local/bin to PATH
source ./activate fails in zsh	Start bash first, then activate
Installer step failed	Read ~/.hermes/logs/install.log, or rerun with --verbose
Options missing after an update	hermes config check, then hermes config migrate
"git data is damaged" during update	Follow the repair steps in the official Updating docs
Anything else	hermes doctor, and attach hermes dump output to a GitHub issue

hermes dump produces a plain-text summary of your setup meant for sharing. API keys show only as set or not set. --show-keys adds the first and last four characters of each key, so leave it off when posting publicly.

A dedicated Mac makes all of this easier: one clean HERMES_HOME for production, one for development, and no laptop sleep in the way. See Hermes on Mac mini, compare plans on the pricing section, or read how to run Hermes Agent 24/7.