Hermes Agent

Run a persistent, self-improving AI agent locally, accessible via Telegram, with support for any LLM provider.

Visit Site
A high-resolution social sharing image preview for Hermes Agent tool.

# Hermes Agent Setup Guide

Cross-Platform Installation with Telegram Integration

> What you'll build: A persistent, self-improving AI agent running on your own machine, accessible from your phone via Telegram — using your choice of AI model.

---

Before You Start

What Is Hermes Agent?

[Hermes Agent](https://hermes-agent.nousresearch.com/) is an open-source autonomous agent built by [Nous Research](https://nousresearch.com/). Unlike a chat interface that resets every session, Hermes:

  • Retains persistent memory across conversations
  • Auto-generates reusable skills from past tasks
  • Runs scheduled automations without your involvement
  • Is reachable from Telegram, Discord, Slack, WhatsApp, CLI, and more
  • Supports any LLM provider — OpenRouter (200+ models), OpenAI, DeepSeek, Nous Portal, or your own endpoint

> Licence: MIT. Source of truth: [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)

---

System Requirements

| Platform | Status | Notes | |---|---|---| | macOS | ✅ Native | Use the built-in Terminal | | Linux (Ubuntu, Debian, CentOS) | ✅ Native | Any standard terminal | | Windows | ⚠️ Via WSL2 | Native Windows is not supported | | Android | ✅ Via Termux | Installer detects Termux automatically |

Minimum model requirement: Your chosen LLM must support at least 64,000 tokens of context. Models below this threshold are rejected at startup.

---

Part 1 — Environment Setup

Windows: Install WSL2 First

If you're on Windows, complete this section before anything else.

  1. Open PowerShell as Administrator and run:

```powershell wsl --install ```

  1. Restart your PC when prompted.
  2. Open the newly installed Ubuntu app from the Start menu — this is your terminal for all subsequent steps.

> Tip: Everything from this point runs inside WSL2/Ubuntu, not in PowerShell.

Verify Your Environment

In your terminal (macOS Terminal, Linux shell, or WSL2 Ubuntu), confirm you can reach the internet:

```bash # Should return JSON — if it hangs or errors, check your network/proxy curl -s https://api.telegram.org | head -c 100 ```

---

Part 2 — Install Hermes Agent

Audit Before You Install (Recommended)

Any time you pipe a script directly to `bash`, it's good practice to read it first:

```bash # Preview the installer before running it curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | cat ```

Once you're satisfied, run the installer:

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

> Note: The official installer URL is the GitHub raw source above. Various vanity URLs (like `hermes-agent.nousresearch.com/install.sh`) redirect here, but always prefer the canonical GitHub source for auditability.

The installer automatically handles:

  • Python virtual environment
  • Node.js
  • `ripgrep` and `ffmpeg` (required for AI tool execution)
  • Global `hermes` command registration

When prompted whether to install `ripgrep` and build tools, type `Y`. Skipping these will break certain agent capabilities later.

Verify Installation

```bash hermes --version ```

If you get `command not found`, refresh your shell environment and try again:

```bash # bash users (Linux / WSL2) source ~/.bashrc

# zsh users (macOS default) source ~/.zshrc ```

Run diagnostics if anything seems off:

```bash hermes doctor ```

---

Part 3 — Configure Hermes

Run the interactive setup wizard:

```bash hermes setup ```

You'll be guided through:

1. Choose an LLM provider.

Hermes supports many providers. Pick what fits your situation:

| Provider | Good For | Notes | |---|---|---| | Nous Portal | Hermes-native models | Subscription-based, tight integration | | OpenRouter | Model variety (200+) | Pay-per-use, easy to switch models | | OpenAI | Familiarity | GPT-4o, o1, etc. | | DeepSeek | Cost-efficient coding tasks | Fast, cheap — requires `deepseek-chat` model | | Your own endpoint | Full control | Any OpenAI-compatible API |

> There is no universally "best" provider — choose based on your cost tolerance, preferred models, and data privacy requirements. You can switch later with `hermes model`.

2. Enter your API key for your chosen provider.

3. When asked about a Messaging Platform, choose Skip — you'll configure Telegram in the next section, more easily.

Your configuration is saved to `~/.hermes/config.yaml`.

---

Part 4 — Create Your Telegram Bot

You need two things from Telegram: a Bot Token and your personal User ID.

Get a Bot Token

  1. Open Telegram and search for `@BotFather`
  2. Send `/newbot`
  3. Choose a display name (e.g., `My Hermes`)
  4. Choose a username — must end in `bot` (e.g., `myhermesbot`)
  5. Copy the Bot Token — it looks like: `1234567890:ABCdef...`

Get Your User ID

  1. Search for `@userinfobot` in Telegram
  2. Send `/start`
  3. Copy the numeric User ID shown (e.g., `987654321`)

Keep both values handy for the next steps.

---

Part 5 — Connect Telegram to Hermes

Configure the Gateway

Add your Telegram credentials to Hermes:

```bash hermes setup gateway ```

Or manually edit `~/.hermes/config.yaml` and add:

```yaml gateway: telegram: enabled: true token: "YOURBOTTOKENHERE" ```

Set User Authorization

This step is critical. Without it, your bot either ignores all messages or accepts messages from anyone.

The correct approach is to whitelist your specific User ID:

```bash echo "TELEGRAMALLOWEDUSERS=YOURNUMERICUSERID" >> ~/.hermes/.env ```

Replace `YOURNUMERICUSERID` with the number you got from `@userinfobot` (e.g., `987654321`).

> ⚠️ Security note: Some guides suggest `GATEWAYALLOWALLUSERS=true` as a quick fix. Do not use this in practice. It disables all authorization — anyone who discovers your bot can interact with your agent, access your files, and trigger automations. The per-user whitelist above takes one extra minute and closes that risk entirely.

Start the Gateway

```bash hermes gateway run & ```

The `&` runs it in the background. To stop it:

```bash pkill -f "hermes gateway" ```

---

Part 6 — Web UI (Optional)

The Hermes CLI is fully capable on its own. A Web UI is useful if you want a visual interface for managing sessions, reviewing memory, or configuring channels without editing YAML.

There are multiple community-built options — none are official Nous Research products:

| Project | Tech Stack | Notes | |---|---|---| | [EKKOLearnAI/hermes-web-ui](https://github.com/EKKOLearnAI/hermes-web-ui) | Vue 3 + TypeScript | Popular, feature-rich, actively maintained | | [nesquena/hermes-webui](https://github.com/nesquena/hermes-webui) | — | CLI parity focus, SSH-tunnel friendly | | [sanchomuzax/hermes-webui](https://github.com/sanchomuzax/hermes-webui) | React 19 + FastAPI | Read-only analytics dashboard |

Evaluate each against your needs. All read from the same `~/.hermes/` data directory.

Installing EKKOLearnAI's Web UI (Example)

As before, audit the script first:

```bash curl -fsSL https://raw.githubusercontent.com/EKKOLearnAI/hermes-web-ui/main/scripts/setup.sh | cat ```

Then install:

```bash bash <(curl -fsSL https://raw.githubusercontent.com/EKKOLearnAI/hermes-web-ui/main/scripts/setup.sh) ```

Start the panel:

```bash hermes-web-ui start ```

Open your browser at [http://localhost:8648](http://localhost:8648).

> WSL2 note: Your services stop when WSL shuts down. On macOS/Linux, the installer typically sets up a background daemon that persists across terminal sessions.

---

Part 7 — Verify Everything Works

Check the Gateway

```bash # Confirm the gateway process is running pgrep -f "hermes gateway" && echo "Gateway is running" ```

Test Telegram

Open your bot in Telegram and send:

``` hello ```

If your agent replies, you're done. 🎉

Test the CLI Directly

```bash hermes chat ```

---

Part 8 — Optional Configuration

Enable Persistent Memory and Skills

Open `~/.hermes/config.yaml` and add:

```yaml skills: enabled: true autoload: true

memory: enabled: true storage: "sqlite" path: "~/.hermes/memory.db" ```

Switch Your Model

At any time, without changing any other configuration:

```bash hermes model ```

This walks you through switching providers or models interactively.

---

Troubleshooting

`hermes: command not found` after install

Your shell hasn't picked up the new PATH. Run: ```bash source ~/.bashrc # bash / WSL2 source ~/.zshrc # macOS zsh ```

Telegram bot receives messages but doesn't respond

  1. Confirm the gateway is running: `pgrep -f "hermes gateway"`
  2. Check your `.env` has the correct User ID whitelisted
  3. Look at gateway logs: `hermes gateway logs`

Network timeout when connecting to Telegram

Telegram's API may be blocked on your network. Test: ```bash curl -s https://api.telegram.org ``` If this fails, you need a proxy or VPN before Hermes can connect.

Bot stops when you close the terminal (WSL2)

WSL2 is a virtual machine tied to your Windows session. To keep it running:

  • Use a terminal multiplexer: `tmux` or `screen`
  • Or run Hermes on a cloud VM (e.g., a $5/mo VPS) and SSH in as needed

Full reset / something is broken

```bash # Stop everything pkill -f "hermes"

# Remove deprecated config variables that cause crashes # WSL2 / Linux: sed -i '/TERMINALCWD/d' ~/.hermes/.env

# macOS: grep -v "TERMINALCWD" ~/.hermes/.env > ~/.hermes/.env.tmp && mv ~/.hermes/.env.tmp ~/.hermes/.env

# Restart hermes gateway run & ```

---

Updating Hermes

Re-running the installer safely updates in place:

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

---

Summary

| Step | What You Did | |---|---| | ✅ WSL2 (Windows) | Linux environment ready | | ✅ Installed Hermes | From the canonical GitHub source | | ✅ Configured a provider | Model of your choice, not locked in | | ✅ Created a Telegram bot | Via BotFather | | ✅ Authorized only yourself | Specific User ID, not open access | | ✅ Started the gateway | Hermes reachable from Telegram |

Official documentation: [hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs) GitHub: [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) Community Discord: [discord.gg/NousResearch](https://discord.gg/NousResearch)

---

This guide is community-maintained and independent of Nous Research. Always verify commands against the official documentation before running them.