Installation

Prerequisites

Requirement	Notes
git	Required to clone the repository. Install with `sudo apt install git` (Debian/Ubuntu), `xcode-select --install` (macOS), or your distro’s package manager.
Python 3.11+	The installer provisions Python automatically via `uv` — you do not need to install it manually.
Linux, macOS, or WSL2	Native Windows is not supported. Use WSL2 on Windows.

Node.js is installed automatically by the one-line installer (used by browser tools and the WhatsApp bridge).

Install

One-line installer (recommended)
Manual install

The installer handles everything: Python, Node.js, all Python dependencies, the mini-swe-agent submodule (terminal backend), and the hermes CLI symlink.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

After it completes, reload your shell:

source ~/.bashrc

Then run the setup wizard:

hermes setup

Installer optionsPass flags after -- when piping through bash:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup

Flag	Description
`--skip-setup`	Skip the interactive setup wizard at the end
`--branch NAME`	Install a specific git branch (default: `main`)
`--dir PATH`	Override the install directory (default: `~/.hermes/hermes-agent`)
`--no-venv`	Do not create a virtual environment

Use manual install if you want to contribute to Hermes, pin a specific commit, or integrate it into an existing environment.

Clone the repository

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

Initialize the mini-swe-agent submodule

mini-swe-agent is the terminal backend. It is required for the agent to run shell commands.

git submodule update --init mini-swe-agent

For RL/Atropos training work, also initialize the optional submodule:

git submodule update --init tinker-atropos

Create a virtual environment with uv

Install uv if you don’t have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then create and activate the environment:

uv venv .venv --python 3.11
source .venv/bin/activate

Install dependencies

uv pip install -e ".[all,dev]"
uv pip install -e "./mini-swe-agent"

If you initialized tinker-atropos:

uv pip install -e "./tinker-atropos"

Symlink the CLI command

mkdir -p ~/.local/bin
ln -sf "$(pwd)/.venv/bin/hermes" ~/.local/bin/hermes

Make sure ~/.local/bin is on your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add the export to your ~/.bashrc or ~/.zshrc to make it permanent.

Run the setup wizard

hermes setup

Updating

Update to the latest version with:

hermes update

This pulls the latest commits, updates Python dependencies, and re-syncs bundled skills. Your config (~/.hermes/config.yaml) and API keys (~/.hermes/.env) are not modified.

Uninstalling

hermes uninstall

This removes the installed files and the hermes symlink. Your ~/.hermes/ directory (config, API keys, sessions, memories) is not deleted automatically — remove it manually if you want a clean slate:

rm -rf ~/.hermes

File locations

All user data lives in ~/.hermes/:

Path	Contents
`~/.hermes/config.yaml`	All settings (model, toolsets, terminal backend, display, etc.)
`~/.hermes/.env`	API keys and secrets
`~/.hermes/SOUL.md`	Agent persona/identity file
`~/.hermes/sessions/`	Conversation history (SQLite)
`~/.hermes/skills/`	User-installed and bundled skills
`~/.hermes/cron/`	Scheduled job definitions
`~/.hermes/logs/`	Gateway and scheduler logs

Get Started

User Guide

Features

Developer Guide

Migration

Prerequisites

Install

Updating

Uninstalling

File locations

Build docs developers (and LLMs) love

Get Started

User Guide

Features

Developer Guide

Migration

​Prerequisites

​Install

​Updating

​Uninstalling

​File locations

Build docs developers (and LLMs) love

Prerequisites

Install

Updating

Uninstalling

File locations