hermes-agent/website/docs/getting-started/installation.md

sidebar_position, title, description

sidebar_position	title	description
1	Installation	Install Hermes Agent on Linux, macOS, or WSL2

Installation

Get Hermes Agent up and running in under two minutes with the one-line installer, or follow the manual steps for full control.

Quick Install

Linux / macOS / WSL2

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

:::warning Windows Native Windows is not supported. Please install WSL2 and run Hermes Agent from there. The install command above works inside WSL2. :::

What the Installer Does

The installer handles everything automatically:

• Installs uv (fast Python package manager) if not present
• Installs Python 3.11 via uv if not already available (no sudo needed)
• Installs Node.js v22 if not present (needed for browser automation and WhatsApp bridge)
• Installs ripgrep if not present (fast file search)
• Installs ffmpeg if not present (audio format conversion for TTS)
• Clones to ~/.hermes/hermes-agent (with submodules: mini-swe-agent, tinker-atropos)
• Creates a virtual environment with Python 3.11
• Installs all dependencies and submodule packages
• Installs WhatsApp bridge npm dependencies
• Seeds bundled skills into ~/.hermes/skills/
• Creates a default SOUL.md personality file
• Sets up the hermes command globally (no venv activation needed)
• Runs the interactive setup wizard

After Installation

Reload your shell and start chatting:

source ~/.bashrc   # or: source ~/.zshrc
hermes setup       # Configure API keys (if you skipped during install)
hermes             # Start chatting!

---

Prerequisites

The only prerequisite is Git. The installer automatically handles everything else:

• uv (fast Python package manager)
• Python 3.11 (via uv, no sudo needed)
• Node.js v22 (for browser automation and WhatsApp bridge)
• ripgrep (fast file search)
• ffmpeg (audio format conversion for TTS)

:::info You do not need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what's missing and installs it for you. Just make sure git is available (git --version). :::

---

Manual Installation

If you prefer full control over the installation process, follow these steps.

Step 1: Clone the Repository

Clone with --recurse-submodules to pull the required submodules:

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

If you already cloned without --recurse-submodules:

git submodule update --init --recursive

Step 2: Install uv & Create Virtual Environment

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv with Python 3.11 (uv downloads it if not present — no sudo needed)
uv venv venv --python 3.11

:::tip You do not need to activate the venv to use hermes. The entry point has a hardcoded shebang pointing to the venv Python, so it works globally once symlinked. :::

Step 3: Install Python Dependencies

# Tell uv which venv to install into
export VIRTUAL_ENV="$(pwd)/venv"

# Install with all extras
uv pip install -e ".[all]"

If you only want the core agent (no Telegram/Discord/cron support):

uv pip install -e "."

Optional extras breakdown

Extra	What it adds	Install command
all	Everything below	uv pip install -e ".[all]"
messaging	Telegram & Discord gateway	uv pip install -e ".[messaging]"
cron	Cron expression parsing for scheduled tasks	uv pip install -e ".[cron]"
cli	Terminal menu UI for setup wizard	uv pip install -e ".[cli]"
modal	Modal cloud execution backend	uv pip install -e ".[modal]"
tts-premium	ElevenLabs premium voices	uv pip install -e ".[tts-premium]"
pty	PTY terminal support	uv pip install -e ".[pty]"
honcho	AI-native memory (Honcho integration)	uv pip install -e ".[honcho]"
mcp	Model Context Protocol support	uv pip install -e ".[mcp]"
homeassistant	Home Assistant integration	uv pip install -e ".[homeassistant]"
slack	Slack messaging	uv pip install -e ".[slack]"
dev	pytest & test utilities	uv pip install -e ".[dev]"

You can combine extras: uv pip install -e ".[messaging,cron]"

Step 4: Install Submodule Packages

# Terminal tool backend (required for terminal/command-execution)
uv pip install -e "./mini-swe-agent"

# RL training backend
uv pip install -e "./tinker-atropos"

Both are optional — if you skip them, the corresponding toolsets simply won't be available.

Step 5: Install Node.js Dependencies (Optional)

Only needed for browser automation (Browserbase-powered) and WhatsApp bridge:

npm install

Step 6: Create the Configuration Directory

# Create the directory structure
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}

# Copy the example config file
cp cli-config.yaml.example ~/.hermes/config.yaml

# Create an empty .env file for API keys
touch ~/.hermes/.env

Step 7: Add Your API Keys

Open ~/.hermes/.env and add at minimum an LLM provider key:

# Required — at least one LLM provider:
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# Optional — enable additional tools:
FIRECRAWL_API_KEY=fc-your-key          # Web search & scraping
FAL_KEY=your-fal-key                   # Image generation (FLUX)

Or set them via the CLI:

hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here

Step 8: Add hermes to Your PATH

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

If ~/.local/bin isn't on your PATH, add it to your shell config:

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Fish
fish_add_path $HOME/.local/bin

Step 9: Run the Setup Wizard (Optional)

hermes setup

Step 10: Verify the Installation

hermes version    # Check that the command is available
hermes doctor     # Run diagnostics to verify everything is working
hermes status     # Check your configuration
hermes chat -q "Hello! What tools do you have available?"

---

Quick-Reference: Manual Install (Condensed)

For those who just want the commands:

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

# Clone & enter
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Create venv with Python 3.11
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# Install everything
uv pip install -e ".[all]"
uv pip install -e "./mini-swe-agent"
uv pip install -e "./tinker-atropos"
npm install  # optional, for browser tools and WhatsApp

# Configure
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

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

# Verify
hermes doctor
hermes

---

Troubleshooting

Problem	Solution
hermes: command not found	Reload your shell (source ~/.bashrc) or check PATH
API key not set	Run hermes setup or hermes config set OPENROUTER_API_KEY your_key
Missing config after update	Run hermes config check then hermes config migrate

For more diagnostics, run hermes doctor — it will tell you exactly what's missing and how to fix it.