How to Install and Set Up Hermes Agent — The Complete Guide

I have set up Hermes Agent more times than I can count — on MacBooks, Ubuntu servers, a HK-based VPS, and even on Android while travelling. Every time I help someone get started, I notice the same problem: the existing guides are either too basic (just the install command) or too scattered (you need four different pages to get the full picture).

This guide fixes that. It covers every install method, every provider option, Telegram setup, the gotchas nobody else documents, and how to actually get value from Hermes once it is running.

By the end you will have a fully working Hermes Agent that you can chat with from your phone via Telegram.

Hermes Agent is an open-source AI agent built by Nous Research. Unlike a standard chatbot, it runs on your own machine or server, connects to whichever AI model you choose, has access to real tools (terminal, browser, file system, web search), and learns and improves over time through a self-generated skills system.

The key differences from tools like ChatGPT or Claude's web interface:

Before installing, make sure you have:

• An operating system: Linux, macOS, Windows (native or WSL2), or Android (Termux). All supported.
• An LLM provider account: You need at least one. The cheapest/easiest options are covered below.
• A model with 64K+ context window: This is the most common gotcha. Hermes injects memory, skills, and system prompts into every request — smaller context windows will hit their limit fast. The installer will warn you if your chosen model is too small.

You do not need to spend much. Here are the most popular options ranked by ease of setup:

The fastest way to get running. One command handles everything — Python, Node.js, ripgrep, ffmpeg, and the Hermes binary itself.

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

After it completes:

source ~/.bashrc   # or: source ~/.zshrc on macOS
hermes             # Start chatting

The installer creates everything under ~/.hermes/ and puts the binary at ~/.local/bin/hermes.

pip install hermes-agent
hermes postinstall   # Installs Node.js, browser tools, ripgrep, ffmpeg

Use pip if you already manage a Python environment and want Hermes in it. Skip postinstall if you only need the core agent without browser automation or audio.

Download the signed installer from the GitHub Releases page. Double-click, done. No terminal required for installation.

The desktop app is the best option if you are on Windows and not comfortable with WSL2, or on macOS and want a clean native install without touching the terminal.

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

Run this in PowerShell as Administrator. The Windows native installer supports CLI, gateway, cron, browser, and MCP. The only thing that requires WSL2 on Windows is the Dashboard terminal pane.

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

The installer auto-detects Termux. Use the .[termux] pip extra if installing via pip on Android.

After installation, run the setup wizard:

hermes setup

This walks you through: 1. Choosing your LLM provider 2. Setting your API key 3. Optionally configuring messaging platforms (Telegram, Discord, etc.)

Fastest path if you use Nous Portal:

hermes setup --portal

This single command handles OAuth login, model selection, and all four Tool Gateway features (Firecrawl, image generation, TTS, browser automation) in one step.

hermes doctor

This is your best friend. It checks every dependency, every API key, every configuration setting, and tells you exactly what is missing and how to fix it. Run it after any setup change.

A healthy output looks like:

✅ Python 3.12.3
✅ Node.js 22.4.0
✅ ripgrep 14.1.0
✅ ffmpeg 6.1.1
✅ Model: anthropic/claude-sonnet-4-6
✅ API key: ANTHROPIC_API_KEY (set)
✅ Gateway: Not configured (optional)

If anything shows ❌, the doctor tells you the exact command to fix it.

If you did not configure a provider during setup, or want to add more:

hermes model

This opens an interactive menu to add providers and API keys. Select your provider, follow the prompts, and Hermes stores the key in ~/.hermes/.env.

To set a model directly:

hermes config set model anthropic/claude-sonnet-4-6
hermes config set ANTHROPIC_API_KEY your-key-here

Important: Your model must support at least 64K context tokens. If you get errors about context length, either switch models or set:

hermes config set model.context_length 65536

If you want to run completely offline with no API costs:

# Install Ollama first: https://ollama.com
ollama pull qwen2.5:32b   # or any 64K+ context model
ollama serve

Then in Hermes:

hermes model
# Select: Custom endpoint
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen2.5:32b
# Context length: 65536

This is where Hermes gets genuinely powerful. Once connected, you can message your agent from anywhere — your phone, your laptop, a group chat — and it responds with full tool access.

1. Open Telegram and message @BotFather
2. Send /newbot
3. Choose a name (e.g., "My Hermes") and a username (must end in bot, e.g., myhermes_bot)
4. BotFather gives you a token that looks like: 7123456789:AAF...
5. Copy and save this token

Message @userinfobot on Telegram. It replies with your numeric user ID (e.g., 123456789). This is how Hermes knows who is allowed to talk to it.

Do not use your username — it must be the numeric ID.

hermes gateway setup

Select Telegram from the menu, paste your bot token and user ID. That's it.

Or add them manually to ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=7123456789:AAF...
TELEGRAM_ALLOWED_USERS=123456789

hermes gateway          # Run in foreground (good for testing)
hermes gateway start    # Run as background service

Then open Telegram, find your bot, and send it a message. It should respond within a few seconds.

If you add the bot to a group and it does not respond:

1. Message @BotFather → select your bot → Bot Settings → Group Privacy → Turn Off
2. Remove the bot from the group and re-add it — this step is mandatory and often missed
3. Alternatively, promote the bot to Group Admin

To keep Hermes running 24/7 even after you close your terminal:

hermes gateway install      # Install as user service (auto-starts on login)
hermes gateway start        # Start it now
hermes gateway status       # Check it is running

On Linux this creates a systemd user service. On macOS it creates a launchd entry. Both restart automatically on crash.

After setup, your Hermes home lives at ~/.hermes/:

~/.hermes/
├── config.yaml     # All non-secret settings (model, TUI preferences, tools)
├── .env            # API keys and secrets (never commit this)
├── SOUL.md         # Agent personality — edit to change how Hermes communicates
├── memories/
│   ├── MEMORY.md   # Facts Hermes saves about your environment and preferences
│   └── USER.md     # Facts Hermes saves about you
├── skills/         # Procedures Hermes learns and saves for reuse
├── cron/           # Scheduled tasks
├── sessions/       # Chat history (SQLite + JSONL)
└── logs/           # Logs (secrets auto-redacted)

The most useful files to know:

• `config.yaml` — open this to change your model, adjust tool settings, or modify how the TUI looks
• `SOUL.md` — edit this to change the agent's personality and communication style
• `MEMORY.md` / `USER.md` — Hermes writes to these automatically as it learns things. You can read and edit them directly.

Once running, these slash commands work inside any conversation — whether you're in the terminal, Telegram, or Discord:

source ~/.bashrc    # Linux
source ~/.zshrc     # macOS

If that does not work, check that ~/.local/bin is in your PATH:

echo $PATH | grep local
# If missing:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Run hermes doctor first — it will pinpoint exactly what is wrong. The most common causes:

• Wrong key type: OpenRouter keys start with sk-or-, OpenAI keys start with sk-. They are not interchangeable.
• Key not saved: Use hermes config set YOUR_KEY_ENV_VAR your-key-value to save it properly
• Telegram User ID wrong: Must be numeric (from @userinfobot), not your @username

Your model's context window is too small. Either:

hermes model   # Switch to a model with 64K+ context
# or
hermes config set model.context_length 65536

During a long conversation, use /compress to reduce the context size without losing the key information.

1. @BotFather → your bot → Bot Settings → Group Privacy → Turn Off
2. Remove the bot from the group entirely
3. Re-add the bot to the group
4. This order matters — skipping step 2 means the privacy change does not take effect

Once Hermes is running, here are the most useful things to explore:

Hermes can learn and save reusable procedures as skills. Browse the community skills marketplace:

hermes skills browse
hermes skills search "github"
hermes skills install github-pr-workflow

Skills are like plugins for specific tasks — PR review, blog writing, data analysis, whatever you need repeatedly.

You can schedule recurring tasks in plain English:

"Check the HKMA website every morning at 8am and send me a summary of any new circulars"

Hermes sets up the cron job, runs it on schedule, and delivers results to your Telegram.

If you want separate configurations for work and personal use:

hermes profile create work
hermes profile use work
hermes setup   # Configure work-specific model and API keys

Each profile has its own config, memories, and skills.

*This guide covers everything you need to get Hermes running and productive. If you run into anything not covered here, the official docs at hermes-agent.nousresearch.com/docs are the authoritative reference. Questions about specific setups? Reach out at sheryarshah.com.*