AI Agent Hermes: What It Is, How to Install and Configure It

Claude Code, Codex, Cursor, OpenClaw—each of these AI agents has its own role. If you need an agent that lives on your server, remembers you between sessions, and answers you on Telegram while you’re riding in a taxi, Hermes Agent fits that role.

Hermes Agent is an open project from Nous Research, and it’s much easier to install than many people think. Here’s what follows: what it is, how much it costs, how to install it on Windows, macOS, or Linux, and how to connect a model and a Telegram bot to it. Everything is based on the official documentation.

What Is Hermes Agent in Plain Language?#

Hermes belongs to the same category as Claude Code or Codex: it’s an AI agent that doesn’t just write responses; it opens files, runs terminal commands, and uses a browser. The difference is in how it’s built: Claude Code is tied to Anthropic models, while Hermes works with any model provider—from Claude and GPT to local models running on your hardware.

The project is young: its GitHub repository was created on July 22, 2025. Even so, as of August 22, 2026, it has more than 234,000 stars and 47,000 forks, making it one of the fastest-growing open projects in this category. The code is fully open under the MIT license: you can read, modify, and use it in your products without royalties.

Two specific mechanisms underpin this “self-improvement”: skills and memory. Skills are procedures the agent writes down after complex tasks and applies the next time. Memory is a file containing facts about you and your environment that gets loaded into every new conversation. Both mechanisms are covered below in a separate section.

How Is Hermes Agent Different from Claude Code and Codex?#

The main differences are summarized in this table:

The table makes the main point clear. Claude Code is suited to tasks that need the strongest model and work in a repository—Anthropic still has the best model-and-tool combination here. Hermes is for when you need an agent “on all the time”: it runs on a server, does something every morning on a schedule, answers you on Telegram, and remembers yesterday’s conversation.

If you’re comparing basic tools, there are separate guides on how to install Claude Code, what Codex from OpenAI is, and the AI coding tools landscape in 2026.

How Much Does Hermes Agent Cost in 2026?#

The easiest option is Nous Portal, the native subscription from the Hermes developers. It covers more than three hundred models and also includes ready-to-use services: web search, image generation, voice synthesis, and a cloud browser. As of August 22, 2026, the plans are:

The second option, which many people overlook, is that you don’t have to sign up for a new subscription at all. Hermes can sign in through OAuth—that is, through an account you already have. ChatGPT and Codex subscriptions, Claude Max, SuperGrok from xAI, Qwen, MiniMax, and GitHub Copilot are supported. Choose a provider in the setup, confirm the sign-in in your browser, and then you pay exactly what you were paying before.

The third option is your own API keys. Anthropic, OpenAI, Google, DeepSeek, Z.AI, Kimi, Alibaba, and about a dozen more providers: enter a key, and usage is billed directly to their account.

The fourth option costs nothing in money, but it does require hardware: a local model through Ollama or LM Studio. This works if you have a powerful computer and don’t want to send data outside it. There’s one condition: the model must have a context window of at least 64,000 tokens, or Hermes will refuse to start with it—the agent needs enough working memory for long tasks.

Payment terms for foreign services aren’t covered here—they’re a separate topic with their own rules, discussed in this guide using Claude Code as an example.

How to Install Hermes Agent on Windows#

If you’re unfamiliar with the terminal, start with the installer. The hermes-agent.nousresearch.com website has download buttons for macOS 12+, Windows 10/11, and Linux. The downloaded file installs both apps at once: the hermes command line and Hermes Desktop—a regular window with chat, files, and settings.

If you’re used to commands, install through PowerShell:

1. Open PowerShell

   Press Win, type PowerShell, and open it. Administrator privileges aren’t required.

2. Run the installer

   iex (irm https://hermes-agent.nousresearch.com/install.ps1)
   

   The script downloads everything it needs: Python 3.11, Node.js 22, the uv package manager, ripgrep, and ffmpeg. If you don’t have Git, it installs its own isolated MinGit build, which is stored separately and doesn’t touch system programs.

3. Restart the terminal and check

   hermes doctor
   

   The command shows what’s installed, what’s missing, and how to fix it. If you see green check marks, everything is installed.

With this installation method, files are stored in %LOCALAPPDATA%\hermes. If you use WSL2, the Linux command in the next section also works inside it—choose whichever is more convenient.

How to Install Hermes Agent on macOS and Linux#

Hermes installs with one command—on a laptop or a server. Here’s the whole process:

1. Check that Git is installed

   git --version
   

   If the command returns a version number, continue. On Linux, also check for curl and xz-utils: on Debian and Ubuntu, install them with sudo apt install curl xz-utils.

2. Run the installer

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

   The script clones the repository into ~/.hermes/hermes-agent, creates a virtual environment, and installs the hermes command in ~/.local/bin. For a server without a GUI and browser automation, there’s a lightweight option: add bash -s -- --skip-browser to the end.

3. Reload the shell and start

   source ~/.zshrc   # on macOS; on Linux, more often: source ~/.bashrc
   hermes
   

When installed as root, files go to system paths—/usr/local/lib/hermes-agent and /usr/local/bin/hermes—which is convenient for a server used by multiple accounts. Settings, keys, and memory still live in each user’s personal ~/.hermes folder.

One note about Hermes Desktop on Linux: to build the app on Debian and Ubuntu, you need the compilers in the build-essential package (sudo apt install build-essential). And if you installed Hermes with the command, you don’t need a separate installer at all—run hermes desktop, and the app will start with your existing settings, sessions, and skills.

How to Connect a Model to Hermes Agent#

The model is the engine for Hermes: the agent doesn’t think on its own; it contacts the model you choose. So the first step after installation is to choose where it will connect:

hermes model

The setup wizard will ask for a provider, sign-in method, and model. There are many options; the main ones are:

If you choose Nous Portal, one command does everything at once:

hermes setup --portal

It opens a sign-in page in your browser. After you confirm, it sets Nous as the provider and enables Tool Gateway—web search, image generation, and voice synthesis without separate keys for each service.

Hermes stores keys and settings separately, and it’s important to understand this from the start. Secrets—API keys and tokens—are stored in ~/.hermes/.env. Regular settings are in ~/.hermes/config.yaml. You don’t need to edit those files by hand: hermes config set puts each value in the right file automatically:

hermes config set model anthropic/claude-opus-4.6

The full setup wizard is hermes setup. It has three modes: a quick setup through Nous Portal, a full setup where you go through each provider and tool yourself, and Blank Slate—a clean installation with everything disabled except the essentials, so you enable only what you need.

How to Check That Hermes Agent Is Working#

After choosing a model, start a conversation:

hermes          # classic interface
hermes --tui    # modern interface, with mouse support and pop-up windows

The welcome banner shows the selected model, enabled tools, and skills. Next, don’t ask “hello, who are you?”—give it a task with a visible result: “show me the five largest folders on the disk” or “look at the current folder and tell me which file is the main project file.” If the agent runs a terminal command and sends back a meaningful answer, the basic setup is working.

The last check is sessions. Exit the conversation and return:

hermes --continue   # or shorter: hermes -c

You should find yourself in the same conversation. This checks that session memory is being written to disk—later, the bot and scheduled tasks will depend on it.

When something doesn’t work, follow this order: hermes doctor (general diagnostics), hermes model (recheck the model and sign-in), hermes setup (rebuild the configuration), hermes sessions list and hermes --continue (check sessions), hermes gateway status (gateway status). This sequence can take you from “everything’s broken” back to a clear state in a couple of minutes.

What Are Skills and Memory in Hermes Agent?#

A Hermes skill is a SKILL.md file with a name, description, and step-by-step procedure: how to assemble a document, open a pull request, or prepare a mailing. The agent reads short descriptions of all skills, then loads the full text only when the task matches—so a hundred installed skills don’t inflate every request. The standard is open, agentskills.io, and the same files work in other agents.

Skills live in the ~/.hermes/skills/ folder. They get there in three ways: a basic set is installed along with the app, ready-made ones can be added from the catalog with hermes skills install, and the agent writes new ones for itself after complex tasks. Each skill automatically becomes a slash command: install the gif-search skill, and /gif-search works in any chat. Installation from the catalog goes through a security check so that someone else’s procedure doesn’t bring in malicious commands.

Memory is even simpler. Two files in ~/.hermes/memories/: MEMORY.md—the agent’s own notes about its environment and conclusions, up to 2,200 characters—and USER.md—your profile: how to respond to you, what you like and dislike, up to 1,375 characters. At the start of every conversation, both files are added to the system prompt, so the agent begins already knowing things about you. The limits are intentionally strict: memory doesn’t sprawl, and the agent decides what to keep and what to discard.

These two pieces—skills plus memory—are the Second Brain: an agent that remembers context and accumulates procedures, working noticeably better each week than on the day it was installed. For guidance on choosing these skills and preventing your agent from becoming a dumping ground, see this guide using Claude Code as an example—the principles are the same.

How to Connect Hermes Agent to Telegram#

Telegram is Hermes’s most popular channel, and the integration is well developed: text, voice messages with transcription, images and files, and replies in groups. Here’s the process:

1. Create a bot with BotFather

   Open @BotFather in Telegram, send /newbot, choose a name and a unique username ending in bot. You’ll receive a token like 123456789:ABCdef...—this is the key to your bot, so store it like a password. If the token leaks, revoke it by sending /revoke to the same BotFather.

2. Find your user ID

   Find your numeric Telegram ID, like 123456789. This is your account number; don’t confuse it with your username. You’ll need it for the access list.

3. Run the gateway setup wizard

   hermes gateway setup
   

   Select Telegram, paste in your token and ID. The wizard will save the settings for you. You can do the same manually with two lines in ~/.hermes/.env: TELEGRAM_BOT_TOKEN=... and TELEGRAM_ALLOWED_USERS=123456789.

4. Start the gateway

   hermes gateway
   

   The bot will be online in a few seconds. Message it and check the response.

Access is closed by default: the bot responds only to IDs on the list. You can give a new person a pairing code—it works for an hour and then expires. The list of pending and approved users is available with hermes pairing list.

There’s one group-chat trap that people often forget. By default, Telegram bots have privacy mode enabled: in a group, a bot sees only commands and replies to its own messages. To make it read everything, turn off the mode with @BotFather (Bot Settings - Group Privacy) or, more simply, make the bot a group admin.

By default, the gateway polls Telegram’s servers itself—which is fine for a home computer or server that’s always on. For cloud platforms that put the machine to sleep when there’s no incoming traffic, there’s webhook mode, where Telegram sends messages to your address.

What Else Can Hermes Agent Do After Installation?#

Here’s what to enable, in order:

1. Scheduled tasks. The gateway has a built-in scheduler: “Every morning at 8, put together a news roundup on my topics and send it to me on Telegram.” Set the schedule with an ordinary phrase, and the results arrive in the same chat.
2. Hermes Desktop. The hermes desktop command opens the app for macOS, Windows, and Linux with the same agent: streaming responses, file previews beside the chat, document drag-and-drop, and a context counter. Sessions are shared—you can start in the terminal and continue in the window.
3. Web panel. hermes dashboard opens a panel in the browser for channels, memory, webhooks, and profiles. Useful when Hermes runs on a server.
4. Subagents. You can delegate a large task to isolated helper agents—each has its own conversation and terminal, so they don’t consume your context.
5. Voice. Voice mode works in the terminal, Telegram, and Discord—you can dictate a task and get a spoken response.
6. Code editor. Through the ACP protocol, Hermes connects to VS Code, Zed, and JetBrains as an agent directly in the editor.

Tools can be turned on and off one at a time with hermes tools, so the agent doesn’t carry everything around with it. When it’s time to move to another machine, hermes backup bundles the whole installation into an archive, and hermes import unpacks it in the new location.

Who Is Hermes Agent For, and Who Should Wait?#

Hermes makes sense to install once you understand what you want an agent to do: sort through documents, build a prototype, manage correspondence, or prepare morning roundups. The tool itself isn’t the important part—the tasks you give it are. There’s a separate guide to tasks for an AI agent on that topic.

It may not be a fit in two cases. First, if you expect to “sign up and have it work”: Hermes needs to be installed and connected to a model. That takes only one command, but you still have to open the terminal. Second, if you don’t have a suitable model and don’t want to figure out a subscription or API keys.

Everyone else should start small: install it, choose a model, have one clean conversation, then add a Telegram bot—and only then schedules and subagents.

What Else Do People Ask About Hermes Agent?#

More resources are available on Ailoot.