How to Install Hermes Agent on Linux, macOS, and WSL2: Complete Setup Guide

Hermes Agent is a powerful command-line AI agent designed for developers who need automation, terminal access, configurable tools, and flexible integrations. If you want a smooth Hermes Agent installation on Linux, macOS, or WSL2, this guide walks through the full process, including requirements, recommended install methods, updates, removal, and important file locations.

This tutorial covers both the fast one-line installer and the manual setup route for advanced users who want more control over their environment. Whether you are evaluating Hermes Agent for daily workflows or preparing a development setup, the steps below will help you get started quickly and correctly.

Prerequisites

Before installing Hermes Agent, make sure your system meets the core requirements.

• Git: Required to download the Hermes Agent repository.
• Python 3.11 or later: You typically do not need to install Python manually because the installer can provision it automatically through uv.
• Supported operating systems: Linux, macOS, and Windows systems using WSL2. Native Windows installation is not supported.

Node.js is also installed automatically by the standard installer. It is used for browser-related tooling and the WhatsApp bridge functionality.

Recommended Hermes Agent Installation

The quickest and easiest way to install Hermes Agent is with the official one-line installer. This method prepares the required Python environment, installs Node.js, fetches dependencies, sets up the terminal backend, and creates the hermes CLI command.

Run the installer with the following command:

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

Once installation finishes, reload your shell configuration. For Bash users, run:

source ~/.bashrc

Then launch the setup wizard:

hermes setup

Installer Options

If you want to customize the installation, you can pass flags after -- when piping the script into Bash.

Example:

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

Available options include:

• --skip-setup: Prevents the interactive setup wizard from running at the end.
• --branch NAME: Installs from a specified Git branch instead of the default main.
• --dir PATH: Changes the default installation directory from ~/.hermes/hermes-agent.
• --no-venv: Skips virtual environment creation.

Manual Hermes Agent Installation

Manual installation is ideal if you plan to contribute to Hermes Agent, lock to a specific commit, or integrate it into an existing Python development workflow.

1. Clone the repository

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

cd hermes-agent

2. Initialize the required submodule

The mini-swe-agent component provides the terminal backend and is necessary for shell command execution.

git submodule update --init mini-swe-agent

If you also need the optional training-related module, initialize it as well:

git submodule update --init tinker-atropos

3. Create a virtual environment with uv

If uv is not already installed, install it first:

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

Then create and activate a Python 3.11 virtual environment:

uv venv .venv --python 3.11

source .venv/bin/activate

4. Install Hermes Agent dependencies

uv pip install -e ".[all,dev]"

uv pip install -e "./mini-swe-agent"

If you initialized the optional training module, install it too:

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

5. Create the Hermes CLI symlink

mkdir -p ~/.local/bin

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

Make sure the local binary directory is included in your PATH:

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

For a permanent configuration, add that export line to your shell profile, such as ~/.bashrc or ~/.zshrc.

6. Run the setup wizard

hermes setup

How to Update Hermes Agent

Keeping Hermes Agent current ensures you receive the latest fixes, dependency updates, and bundled skill changes. To upgrade to the newest version, run:

hermes update

This command updates the local installation, refreshes Python packages, and syncs included skills. Your personal configuration in ~/.hermes/config.yaml and secrets stored in ~/.hermes/.env remain unchanged.

How to Uninstall Hermes Agent

If you need to remove Hermes Agent from your machine, use the uninstall command:

hermes uninstall

This removes the installed application files and CLI symlink. However, your user data directory is preserved by default. If you want to erase all saved settings, sessions, memories, and credentials, delete the data folder manually:

rm -rf ~/.hermes

Hermes Agent File Locations

Hermes Agent stores user-specific data in the ~/.hermes/ directory. Knowing these locations is useful for backup, troubleshooting, and advanced configuration.

• ~/.hermes/config.yaml: Main configuration file for models, toolsets, terminal backend, interface settings, and more.
• ~/.hermes/.env: Stores API keys and sensitive environment variables.
• ~/.hermes/SOUL.md: Defines the agent persona and identity.
• ~/.hermes/sessions/: Contains conversation records stored in SQLite.
• ~/.hermes/skills/: Holds built-in and user-added skills.
• ~/.hermes/cron/: Stores scheduled job definitions.
• ~/.hermes/logs/: Includes scheduler and gateway logs.

Conclusion

Installing Hermes Agent is straightforward, especially with the official one-line installer. For most users, the automated setup is the fastest path to a working CLI AI agent environment. Advanced users can choose the manual route for deeper customization, development work, or environment control.

By following this Hermes Agent installation guide, you can confidently set up, update, manage, and remove the tool while understanding where its configuration and data are stored. If you are ready to begin using its features, the next step is to run hermes setup and start your first session.