How to Install Hermes Agent: A Beginner's Guide

You've heard about Hermes Agent, want to try it out, and are now sitting in front of your terminal. And you wonder:

Where do I start?

No surprise. Hermes Agent now counts among the most popular self-improving AI agents. Over 177,000 GitHub stars, a broad community, and an almost ridiculous number of integrations. But a proper step-by-step guide? That one's harder to find than you'd think.

Hermes Agent runs on macOS, Linux servers, and even on Termux on Android. The installation is much smoother than with most agent frameworks. But there are a few pitfalls that nobody tells you about when you just copy the one-liner from the docs.

In this guide, I'll show you step by step how to install Hermes Agent, connect an LLM provider, and get your first channel running. Whether you're on macOS, Linux, or Windows.

What Is Hermes Agent Actually?

A quick overview in case you're not exactly sure what this is about.

Hermes Agent is an open-source AI agent from Nous Research, released under the MIT license. The tagline "The Agent That Grows With You" hits the core. Hermes learns as you use it, persists knowledge across sessions, and builds a deeper model of your workflow over time.

And no.

Hermes Agent isn't just another coding tool like Claude Code or GitHub Copilot. Hermes is a universal personal AI agent. That means you can use it through Telegram, Discord, Slack, WhatsApp, Signal, Email, Microsoft Teams, Home Assistant, or directly from the command line.

You ask it via message to do something, and it gets done. Research, summaries, web searches, image generation, browser control. If you're mainly looking for coding support, a comparison of AI coding tools might be more helpful. Hermes is at its best where you want to work long-term with an agent that knows you.

At its core, it's a personal AI assistant that actually gets better over time.

What You Need for the Hermes Agent Installation

Check these points quickly before you start.

Python 3.11 or newer. This is the most important prerequisite. If you're unsure which version you have, open your terminal and type python --version or python3 --version. Does it show something below 3.11? Then you need to update.

On macOS, the easiest way is through Homebrew, on Linux through your distro's package manager.

brew install python@3.11

Your operating system. Hermes Agent runs on:

• macOS 13 (Ventura) or newer
• Linux with glibc 2.31+
• Windows 10/11 (native or through WSL2)
• Android through Termux (yes, seriously, it runs surprisingly well)

An account with an LLM provider (optional but recommended). You need access to an AI model. Hermes supports over 30 providers, including Anthropic Claude, OpenAI, Google Gemini, OpenRouter, and the Nous Portal. Or you can use Ollama for local models. That's completely free. More on that later.

That's all you need. Let's go!

Installing Hermes Agent on macOS and Linux

The fastest method is the official one-liner. Open your terminal and paste the following command:

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

The script checks your Python installation, downloads Hermes Agent through uv (a fast Python package manager), sets up a virtual environment, and configures the gateway service. The gateway then runs as a background process and handles communication with the channels.

If you (understandably) prefer not to blindly run a script from the internet, there's an alternative through pip.

pip install hermes-agent
hermes setup

Both paths lead to the same result. The pip method just gives you a bit more control over what happens. If you use Conda instead of pip, it works the same way.

Once the installation is done, you can start the setup wizard.

hermes setup --portal

Portal mode is the easiest way to get started. An OAuth sign-in to the Nous Portal sets the default provider and unlocks all four Tool Gateway tools (web search, image generation, text-to-speech, and Cloud Browser). If you'd rather use Claude or OpenAI directly, you can switch the provider later via hermes model.

Installing Hermes Agent on Windows

Here Hermes has an advantage over most agent frameworks.

Hermes Agent runs natively on Windows. You don't need WSL2 (unless you want it). Download Python 3.11+ from python.org and install it. Make sure "Add Python to PATH" is checked during installation.

After that, open PowerShell or the Command Prompt and install Hermes through pip.

pip install hermes-agent
hermes setup --portal

Native CLI, gateway, TUI, and all tools work on Windows. The channel integrations (Telegram, Discord, etc.) also run without issues.

If you prefer WSL2 because you already have Linux workflows, that works too. Open PowerShell as administrator.

wsl --install

After that, restart your computer and open the WSL terminal (Ubuntu by default). From here, the installation is identical to Linux.

Setting Up Hermes Agent (LLM Provider and Model Selection)

After installation, you have two things to do. Connect an LLM provider and pick a model. The hermes setup --portal command does this in one step with the Nous Portal as provider. If you want a different provider, use the interactive wizard hermes model, which covers OAuth flows, API keys, and endpoints for over 30 supported providers.

hermes model

Configuring Anthropic Claude

If you already have an Anthropic account, Claude is the easiest choice. In the hermes model wizard, pick Anthropic as the provider and decide between OAuth (for Claude Pro/Max plans) or direct API key entry.

With OAuth, you're redirected to a webpage, log in, and give Hermes permission to send requests on your behalf. Done. If you enter the API key directly, it's stored securely in the configuration at ~/.hermes/config.json.

Configuring OpenAI GPT

Same game for OpenAI. Run hermes model, pick OpenAI, and enter your API key. Or set the key as an environment variable instead.

export OPENAI_API_KEY="your-key"
hermes model

Hermes supports GPT-5.5, GPT-5.4, and GPT-5-Codex, as well as older models like GPT-4.1 and GPT-4o. The model you want to use can be configured per skill or set as a global default.

Local Models with Ollama

The best choice for privacy-conscious setups. Download Ollama from ollama.com, install a model (e.g., Qwen 2.5 Coder or Llama 3.3), and connect it to Hermes.

ollama pull qwen2.5-coder:32b
hermes model

In the wizard, pick Ollama as the provider and enter the endpoint (default is http://localhost:11434). Hermes automatically detects all models you've installed in Ollama. GPU offloading runs on its own on macOS and Linux. You don't need to configure anything.

Getting Started with Hermes Agent

Everything set up? Then try it out.

The fastest way to try Hermes is the command line.

hermes chat

This drops you into an interactive session. Ask something simple like "Summarize the most important AI news from the past week" and see what happens. Hermes uses the configured model, calls the web search tool if needed, and replies.

If you want to use multi-channel integration, Telegram is the easiest way to start. The gateway setup is an interactive wizard that walks you through all supported platforms.

hermes gateway setup

For Telegram, you need a bot token from the Telegram BotFather (free, created in 2 minutes) and you enter it in the wizard. After that, you write a message to your Hermes bot and the agent replies just like in the command line, only this time via Telegram.

Discord, Slack, Signal, Email, Microsoft Teams, and Home Assistant work the same way in the same wizard. For WhatsApp and Slack, there are also dedicated top-level commands (hermes whatsapp and hermes slack) with a few more setup options.

Common Installation Errors (and How to Fix Them)

These errors come up in almost every first installation. Here are the most common problems and what you can do about them.

"hermes: command not found"

The classic. After installation, your terminal can't find the command. This is almost always a PATH issue. Close the terminal and reopen it. If that doesn't help, check whether the pip user bin directory is in your PATH.

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

Python Version Too Old

If you get an error message related to Python, check your version with python --version. Anything below 3.11 is too old. On macOS, update via Homebrew; on Linux, through your package manager.

sudo apt install python3.11 python3.11-venv python3-pip

Build Tools Missing (Linux)

On Linux, you may need additional packages. If the build fails, install:

sudo apt install build-essential python3-dev git

API Key Not Recognized

If Hermes doesn't accept your API key, check the configuration file.

cat ~/.hermes/config.json

Make sure the key is stored correctly under the right provider. Typos are the most common source of errors. If you want to be safe, set it as an environment variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.).

Channel Connection Fails

If a channel (Telegram, Discord, Slack) doesn't start, the gateway service is probably not running. Check that with:

hermes gateway status

If the gateway isn't running, start it manually with hermes gateway start. With Telegram bots, the token is often mistyped, or the bot wasn't activated correctly with BotFather.

Security Notes You Should Know

Hermes Agent is a lot more privacy-friendly than many other agent frameworks.

All data stays on your machine by default. No telemetry, no cloud lock-in, no hidden data leaks. That's one of the main reasons Hermes has gotten so popular. Anyone working under GDPR has way less stress here than with cloud agents.

Still, there are a few points you should watch.

As soon as you use cloud LLMs (Claude, GPT, Gemini), your prompts go to those providers. That's normal, but important to know. If you want absolute privacy, combine Hermes with Ollama. Then not a single token leaves your machine.

hermes update

My security rules for Hermes Agent.

1. Always use the latest version; new releases come out weekly
2. For sensitive workflows, use local models through Ollama instead of cloud LLMs
3. Set channel permissions as tightly as possible (e.g., only allow the Telegram bot for your user ID)
4. For API costs, set a monthly limit with the provider

What Does Hermes Agent Cost?

The software itself costs nothing. Hermes Agent is completely open source under the MIT license.

The actual costs come from the AI models you use in the background. Those are in your control.

Typical costs with normal usage run $5 to $30 per month for API calls (depending on model and intensity). That's comparable to a ChatGPT Plus subscription. If you use Claude Sonnet 4.6, you're more likely to land at $10 to $20.

If you want to go completely free, install Ollama and use local models. Then you really pay nothing, apart from the electricity for your computer.

Conclusion

That's it. You've installed Hermes Agent, connected an LLM provider, and know what to watch out for.

The installation is much smoother than with most agent frameworks. Native Windows support, Python instead of the endless Node version conflicts, and a sensible setup tool make getting started fair. What makes Hermes really special, though, you only notice after a few weeks of use, when the agent starts to know your preferences and makes proactive suggestions.

If you want to go deeper, check out skill development next. Building your own skills is the real aha moment with Hermes. If you're not sure whether Hermes is the right tool for you, my comparison of the best OpenClaw alternatives can help with the decision. Hermes is listed there as the most popular adaptive agent.