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
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 — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, and global hermes command setup. It finishes by running the interactive setup wizard to configure your LLM provider.
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)
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
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.