Hermes Agent: A Beginner’s Guide to Getting It Running and Configured

I have spent the last couple weeks running Hermes Agent on my home server, and the experience convinced me that most people who would benefit from this tool never get past the first install step. Not because it’s hard. It’s not. But the documentation assumes a comfort level with terminals and config files that not everyone has going in.

This guide walks through the whole thing from scratch. I have installed Hermes on three different machines over the past two weeks. By the end, you will have a running Hermes instance, a model configured, and the option to connect it to a messaging platform so you can talk to it from your phone.

What Hermes Agent Actually Is

Before touching any commands, it helps to understand what you are actually installing.

Hermes Agent is an open source autonomous AI agent built by Nous Research. The tagline is “the agent that grows with you,” and that description is pretty accurate. Unlike a standard chatbot that forgets everything when the window closes, Hermes maintains persistent memory across sessions. It builds a library of “skills” over time based on tasks you give it, and it can reach you on messaging platforms like Telegram, Discord, or Slack.

The project is open source under the MIT license, meaning you can read the code, self-host everything, and modify it however you want. Your data stays on your own machine or server.

It is not a coding assistant tethered to an IDE. It is closer to a personal agent that you deploy and then interact with however you want, doing tasks in the background and reporting back to you.

What You Need Before Starting

Hermes runs on Linux, macOS, and WSL2 on Windows. If you are on a Windows machine without WSL2 set up, do that first. The agent does not run natively in PowerShell or CMD.

You will also need:

An API key from at least one AI provider (Anthropic, OpenAI, OpenRouter, or Ollama for local models)
A basic comfort level typing commands into a terminal
About 15 to 20 minutes

That’s genuinely it. Hermes handles the rest of the installation automatically.

Step 1: Running the Installer

Open your terminal (or WSL2 if you’re on Windows) and run the one-line installer:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The script checks for dependencies, downloads what it needs, and sets everything up. When it finishes, reload your shell:

source ~/.bashrc

If you use zsh, swap that for source ~/.zshrc.

To confirm everything went through, run:

hermes --version

You should see a version number. If you see a “command not found” error, your shell did not pick up the new path. Log out and back in, then try again.

If you want to double-check that your environment is healthy, Hermes ships with a diagnostic command:

hermes doctor

This checks all the required pieces and tells you about anything that’s missing or misconfigured.

Step 2: Running the Setup Wizard

Once installed, the fastest way to configure everything is through the interactive setup wizard:

hermes setup

The wizard walks you through:

Choosing your AI provider
Entering your API key
Selecting a model
Basic preferences

This is the recommended path for beginners. The wizard handles all the file writes for you, so you don’t need to touch config files manually.

That said, understanding where those files live is useful for troubleshooting later.

Understanding the Config Files

Hermes stores all its settings in a hidden folder in your home directory: ~/.hermes/

Inside that folder, two files do most of the work:

~/.hermes/config.yaml holds non-sensitive settings: your model selection, which tools are enabled, memory settings, and similar preferences. You can open and edit this in any text editor.

~/.hermes/.env holds secrets: API keys, bot tokens, and anything else that should never appear in a log or a git repository.

The separation matters. If you share your config for troubleshooting, you share config.yaml. The .env file stays private.

You can update individual values without opening files directly by using the CLI:

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

The agent knows whether a value is a secret and routes it to the right file automatically.

Step 3: Connecting Your API Key

If you went through hermes setup, your key is already in. If you skipped it or want to add a second provider, here is how to set keys manually.

OpenRouter (Recommended for Beginners)

OpenRouter is a good starting point because it gives you access to many different models under one API key. You pay per token used rather than committing to a subscription.

Go to openrouter.ai and create an account
Go to Keys in your dashboard and create a new key
Copy the key and run:

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

Anthropic

If you have an Anthropic account and want to use Claude directly:

hermes config set ANTHROPIC_API_KEY sk-ant-your-key-here

OpenAI

hermes config set OPENAI_API_KEY sk-your-key-here

Local Models via Ollama

If you are running models locally with Ollama, Hermes supports that too. Set your endpoint:

hermes config set OLLAMA_BASE_URL http://localhost:11434

For local models, keep in mind that Hermes needs a model with at least 64,000 context tokens to perform well. Small models tend to struggle with complex agentic tasks and may produce unreliable tool calls.

Step 4: Picking a Model

With your API key in place, choose which model Hermes should use:

hermes model

This opens an interactive selector that lists the models available through your configured providers. Scroll through and select one.

For most people starting out, a solid choice is one of the Claude Sonnet models via Anthropic or OpenRouter. I tested Claude 3.5 Sonnet through OpenRouter and it handled complex instructions without the tool-call failures I saw with smaller models. The large context window is the reason Hermes needs it.

If cost is a concern, I compared pricing across models before settling on my setup. Claude Haiku costs roughly $0.25 per million input tokens versus $3.00 for Claude 3.5 Sonnet. For basic tasks, the savings add up quickly. Smaller GPT-4o variants fall somewhere in between.

You can change your model at any time by running hermes model again. The change takes effect immediately without restarting anything.

Step 5: Starting Hermes

With everything configured, you can start the agent in a couple ways depending on how you want to interact with it.

Classic CLI

The simplest option is to launch the standard command-line interface:

hermes

This drops you into a conversation with the agent. Type a task, hit enter, and watch it work.

Terminal UI (TUI) Mode

If you want a slightly richer terminal experience with mouse support, modal overlays, and non-blocking input:

hermes --tui

The TUI mode is useful when you want to run longer tasks and monitor progress without the output scrolling past you.

Step 6: Connecting to a Messaging Platform

This is where Hermes gets genuinely interesting. Rather than only working through the terminal, you can connect it to a messaging platform and talk to it like a contact on your phone.

Supported platforms include Telegram, Discord, Slack, WhatsApp, and Signal.

I’ll walk through Telegram since it’s the most straightforward.

Setting Up the Telegram Gateway

Part 1: Create a Telegram Bot

Open Telegram and search for @BotFather
Send /newbot to start the creation flow
Give your bot a display name (anything you like)
Give your bot a username ending in bot (example: myhermes_bot)
BotFather will reply with your Bot Token. Copy it and keep it somewhere safe.

Part 2: Get Your Telegram User ID

Hermes needs to know which Telegram account to trust, so it doesn’t respond to arbitrary people who message your bot.

Search for @userinfobot on Telegram
Send it any message
It will reply with your numeric User ID. Copy that number.

Part 3: Configure the Gateway

Run the gateway setup:

hermes gateway setup

Select Telegram, then enter your Bot Token and User ID when prompted. Alternatively, you can add them manually to ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=your_token_here
TELEGRAM_ALLOWED_USERS=your_numeric_id_here

Part 4: Start the Gateway

hermes gateway

The agent is now listening for messages from your Telegram account. Open Telegram, find your bot, and send it a task.

From here, you can run automations from your phone, ask it to look something up, or give it recurring tasks while you’re away from your desk.

Keeping Hermes Running Persistently

If you want Hermes to stay active even when you close your terminal session, run it inside a screen or tmux session:

# Using screen
screen -S hermes
hermes gateway

# Detach with Ctrl+A then D

Or on a Linux server, you can set it up as a systemd service so it starts automatically on boot. The Hermes documentation covers this in more detail.

Understanding Skills and Memory

Two features separate Hermes from a standard chatbot: persistent memory and skills.

Persistent memory means Hermes remembers context between sessions. If you told it last week that your main project is in /home/you/projects/webapp, it will still know that today. It uses FTS5 full-text search to recall relevant past conversations.

Skills are something different. When Hermes completes a task successfully, it can extract the sequence of steps that worked and save it as a reusable skill document. Think of skills as a growing playbook: if you asked it to generate a weekly report from your data folder last Tuesday, it might save that workflow as a skill and use it automatically next time you ask for the same thing.

You don’t have to actively manage skills. They accumulate in the background as you use the agent. The longer you run it, the better it gets at the specific things you ask of it.

Useful Commands to Know

Here is a quick reference for the commands you will use most often:

Command	What it does
`hermes setup`	Run the interactive configuration wizard
`hermes model`	Switch your AI model or provider
`hermes config set KEY VALUE`	Update a single config value
`hermes gateway`	Start the messaging gateway
`hermes gateway setup`	Configure a messaging platform
`hermes doctor`	Run environment diagnostics
`hermes --tui`	Launch in Terminal UI mode
`hermes --version`	Check your installed version

Common Beginner Mistakes

Using a model with too small a context window. Hermes needs at least 64K tokens of context to handle complex tasks reliably. If you pick a cheap small model and find the agent producing weird results or hallucinated tool calls, model size is usually the reason.

Leaving your API key in config.yaml instead of .env. The setup wizard handles this correctly, but if you’re editing files manually, put API keys only in .env.

Not reloading the shell after install. If hermes gives a command not found error right after install, run source ~/.bashrc (or ~/.zshrc) before assuming something went wrong.

Trying to run Hermes in native Windows PowerShell. It needs Linux/macOS or WSL2. This is the most common point of confusion for Windows users.

A Good First Task to Try

Once everything is running, a simple first task to test the setup is a research query:

Find the latest release notes for Hermes Agent from the GitHub repository and summarize what changed

This tests that your model connection works, that Hermes can browse the web, and that it can return a coherent response. I ran this exact query after my first install and it returned a clean summary of the latest three commits. If that works for you, you are in good shape.

From there, give it something more personal: schedule a daily briefing, have it monitor a folder for new files, or ask it to keep notes on a project you’re working on.

If you want to go further, try connecting Hermes to a self-hosted n8n workflow(https://veduis.com/blog/automating-business-workflows-n8n-make-zapier/) and have it trigger automations based on messages you send. Our API design patterns guide also covers how to build custom endpoints that Hermes can call through its tool system.

If you are running models locally, our guide to local LLMs versus cloud AI breaks down the privacy and cost trade-offs in detail. It covers Ollama setup, hardware requirements, and when cloud APIs still make more sense.

For teams that want to self-host more than just an AI agent, self-hosted business tools compares open-source replacements for Slack, Notion, and Google Workspace with actual deployment steps and cost numbers.

Developers integrating AI into their workflow should read our MCP server installation guide. Hermes supports MCP tool integrations, and the guide covers manual setup plus the 1 Click MCP Installer extension for VS Code.

Where to Go from Here

The official Hermes Agent documentation covers advanced topics including Docker sandboxing, SSH backends, subagent delegation, and MCP tool integrations. The GitHub repository is the authoritative source for changelogs and the latest features.

The Nous Research Discord is also active if you run into something this guide doesn’t cover.

The setup takes about 20 minutes. The value compounds the longer you run it. Start small, give it a few recurring tasks, and let the skill library build up before you throw anything complicated at it.

Conclusion

Hermes Agent is not a magic solution. It is a tool that rewards consistent use. The persistent memory and skills system mean it gets better the longer you run it, but that improvement requires giving it real tasks and letting it learn from the outcomes.

Start with the setup wizard, connect one messaging platform, and give it a simple recurring task. Within a week, you will have a useful assistant that knows your preferences. Within a month, the skill library will handle common workflows without you needing to explain them again.

The 20 minutes spent on initial setup pays for itself quickly. The key is starting small and building up rather than trying to automate everything on day one.