Hermes Agent is an open-source AI agent from Nous Research. It runs in the terminal and can do more than a regular chatbot: it can inspect files, execute commands, use external tools, and remember previous sessions.

In this post, I will cover the shortest path from a fresh machine to a working Hermes Agent session.

Hermes can execute commands and modify files using the permissions of your user account. Install and run it as a normal user, keep command approvals enabled, and start in a directory that does not contain sensitive files.

Installing Hermes Agent

Linux, macOS, or WSL2

Open a terminal and run the official installation script:

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

The installer downloads Hermes, creates its Python environment, installs the required supporting tools, and launches the setup wizard.

When the installation finishes, reload your shell:

source ~/.bashrc

If you use Zsh instead of Bash, run:

source ~/.zshrc

Opening a new terminal window has the same effect.

Windows

Open PowerShell and run:

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

Close and reopen PowerShell when the installer finishes so that the hermes command is available.

On macOS and Windows, you can alternatively install the graphical Hermes Desktop application.

Connecting an AI Model

Hermes needs an AI model provider before it can answer prompts. The simplest option is Nous Portal:

hermes setup --portal

This opens a browser for authentication and configures both a model and the Nous Tool Gateway.

If you prefer to use an API key from another provider, run the general setup wizard instead:

hermes setup

Follow the prompts to choose your provider and model. Hermes supports providers such as OpenAI, Anthropic, OpenRouter, and custom OpenAI-compatible endpoints. You can change the selected provider later with:

hermes model

Starting Your First Session

Start Hermes from a directory you are comfortable allowing it to inspect:

mkdir ~/hermes-test
cd ~/hermes-test
hermes

You can now enter a prompt. For a safe first test, try:

Create a file called hello.txt containing a short greeting.

Hermes should explain what it wants to do and ask for approval before using the terminal or changing a file. Approve the action, then verify the result:

cat hello.txt

That is it: Hermes is installed, connected to a model, and able to use tools.

To leave the session, press Ctrl+C or enter /exit. You can resume your most recent session later with:

hermes --continue

Understanding the Main Hermes Files

Hermes keeps its global settings and data in ~/.hermes/. After the first setup, the most important parts look roughly like this:

~/.hermes/
├── SOUL.md
├── config.yaml
├── .env
├── auth.json
├── memories/
├── skills/
├── sessions/
└── logs/

Here is what each one does:

  • SOUL.md defines the agent’s identity, personality, tone, and communication style. Hermes creates a starter version automatically. Edit this file if you want Hermes to be more concise, more technical, more conversational, or to follow other preferences that should apply everywhere.
  • config.yaml contains non-secret settings such as the selected model, enabled tools, terminal behaviour, and memory options. The safest way to change it is with hermes config rather than editing the YAML manually.
  • .env stores API keys, tokens, and other secrets. Do not share or commit this file to Git.
  • auth.json contains OAuth credentials for providers such as Nous Portal. Treat it as a secret as well.
  • memories/ contains the persistent MEMORY.md and USER.md files. Hermes uses them to remember useful facts, your preferences, and things it has learned between sessions.
  • skills/ contains reusable instructions that teach Hermes how to perform particular tasks.
  • sessions/ and logs/ contain saved session data and diagnostic logs.

For example, you can open the personality file with:

nano ~/.hermes/SOUL.md

A simple customization could look like this:

You are a practical technical assistant.
Be concise, explain commands clearly, and say when you are uncertain.
Prefer safe and reversible actions.

Start a new Hermes session after editing the file. SOUL.md should contain stable instructions about who the agent is and how it communicates, not details about one particular project.

For project-specific instructions, create an AGENTS.md file in the project directory instead:

# Project Instructions

- This is a Hugo blog.
- Blog posts are stored in `content/posts/`.
- Run `hugo` after changing content.
- Do not publish draft posts.

Hermes discovers AGENTS.md when it works in that directory. This keeps project rules with the project while leaving the global personality reusable everywhere.

Connecting Hermes to Telegram

Using Hermes through a messaging application means you can reach your agent from a phone or another computer without opening a terminal. Hermes supports several platforms, but Telegram is probably the simplest place to start. It supports normal messages, images, files, voice messages, and streaming responses without requiring you to configure a public web server.

Before continuing, make sure Hermes already works in the terminal. The computer running Hermes must also remain powered on and connected to the internet for the bot to respond.

Create a Telegram Bot

Open Telegram and start a conversation with @BotFather, Telegram’s official bot-management account.

  1. Send /newbot.
  2. Choose a display name for the bot.
  3. Choose a unique username ending in bot, such as my_home_hermes_bot.
  4. Copy the API token returned by BotFather.

The token looks similar to this:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Treat this token like a password. Anyone who has it can control your Telegram bot. If it is ever exposed, use /revoke in BotFather and generate a replacement.

Configure the Hermes Gateway

Run the interactive gateway wizard:

hermes gateway setup

Select Telegram and paste the bot token when requested. The wizard shows which messaging platforms are already configured and offers to start or restart the gateway when setup is complete.

For an initial test, you can also run the gateway in the foreground:

hermes gateway

Keep this terminal open while testing. Open your new bot in Telegram, press Start, and send it a message. An unknown user receives a temporary pairing code instead of immediate access.

Approve that code from the machine running Hermes:

hermes pairing approve telegram YOUR_PAIRING_CODE

Now send the bot a normal message:

Hello! Tell me which model you are currently using.

You can also send /status to inspect the session or /new to start a fresh conversation.

Keep the Gateway Running

On Linux or macOS, Hermes can install the gateway as a user service:

hermes gateway install
hermes gateway start
hermes gateway status

The service keeps the Telegram connection running in the background. If the bot stops responding, check its status and restart it:

hermes gateway restart
hermes gateway status

On systems where a background service is not available, leave hermes gateway running in a terminal or follow the platform-specific instructions in the messaging gateway documentation.

Only approve pairing requests that you initiated. A person authorized to use the bot may be able to ask Hermes to access files or run tools on its host machine.

If Something Does Not Work

Run the built-in diagnostic:

hermes doctor

For the most common problems:

  • If hermes is not found, open a new terminal and try again.
  • If authentication fails, rerun hermes setup --portal or hermes model.
  • If the agent can chat but cannot use a tool, follow the recommendation printed by hermes doctor.

You can update Hermes at any time with:

hermes update

Once the basic terminal session works, the official Hermes Agent documentation covers optional features such as messaging gateways, skills, browser tools, voice mode, and local models.