Installation guide

How to Install and Use Hermes: A Quick Start from the Local CLI to Feishu Integration

Apr 13, 2026

If you want to install Hermes and start using it, the shortest path is really just three steps:

Run the official installation command
Start the CLI in your terminal with hermes
If you want to keep using it in Feishu, then configure hermes gateway setup

This article does not try to explain every Hermes capability all at once. Instead, it helps you complete the most important beginner loop first: install it, get it running, start using it, and then connect it to one of the most common messaging-platform scenarios.

What Hermes is and who it is for

Hermes Agent is an AI agent that you can use either from a local terminal or through a messaging-platform gateway.

For most developers, it has two common entry points:

CLI: Type hermes in your terminal to enter the interactive interface directly.
Messaging Gateway: Run hermes gateway, then chat with it from platforms such as Feishu, Telegram, Discord, and Slack.

If your goal right now is simply to get started quickly, do not reverse the order. Start with this path instead:

Install Hermes first
Verify it works from the CLI first
Then decide whether you want to connect a messaging platform

This makes problems easier to diagnose and is more suitable for people using Hermes for the first time.

What to know before installing Hermes

According to the Hermes README, the official quick-install path supports these environments:

Linux
macOS
WSL2
Android via Termux

Notes for Windows users

Hermes does not currently support running directly on native Windows. If you are using Windows, the recommended approach is to install WSL2 first and then run the installation command inside WSL2.

It is best to make this clear at the beginning, because many installation failures are not caused by the command itself, but by using an unsupported runtime environment.

How to install Hermes

The quick installation command provided in the Hermes README is:

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

This command runs the official installation script and handles platform-specific initialization steps.

Reload your shell after installation

Once installation finishes, reload your shell environment first. The most common command is:

source ~/.bashrc

If you use zsh, you can use:

source ~/.zshrc

How to confirm Hermes is installed correctly

The most direct way to check is to run:

hermes

If you want additional confirmation that your configuration and dependencies are working, you can also run:

hermes doctor

hermes doctor is especially useful in these situations:

The command behaves abnormally after installation
Model configuration fails
The gateway fails to start
You are not sure whether your environment dependencies are complete

How to start using Hermes for the first time

Start with the CLI

If you just want to confirm as quickly as possible that Hermes works, the simplest method is:

hermes

This launches the interactive Hermes CLI. For first-time Hermes users, it is also the most recommended starting point, because you can verify the most essential things first:

Whether the command is actually available
Whether the current model configuration works properly
Whether the terminal toolchain is working correctly
Whether the interaction style matches what you need

These commands are enough for your first round of setup

The Hermes README lists several high-frequency commands, and together they form a practical first-use path:

hermes model
hermes tools
hermes config set
hermes setup
hermes update
hermes doctor

If you are not sure what each one does, remember them like this:

hermes model: choose or switch models
hermes tools: view and configure currently available tools
hermes config set: change specific configuration items
hermes setup: run the full initialization wizard once
hermes update: update Hermes
hermes doctor: troubleshoot problems

For beginners, the most practical order is usually:

Run hermes model first
If you want to configure all common options at once, then run hermes setup

The two most common ways to use Hermes

1. Use Hermes in the terminal as a daily development assistant

CLI mode is a good fit for these scenarios:

Ask questions directly while writing code locally
Inspect projects, edit files, and run commands
Do one-off debugging or review work
Collaborate continuously in the current working directory

Its biggest advantage is that it is the shortest path: no extra platform integration, no bot configuration to handle up front, and it is the best way to build your first set of usage habits.

2. Use Hermes through a messaging platform

If you want to chat with Hermes on platforms such as Feishu, Telegram, or Discord, you need to use the messaging gateway.

The most common entry commands are:

hermes gateway setup
hermes gateway

Specifically:

hermes gateway setup is used for interactive platform configuration
hermes gateway is used to start the gateway process

According to the official documentation, the gateway is a unified background process that connects your configured platforms, manages sessions, and handles features such as cron jobs.

Using Feishu as an example: how to connect Hermes to a messaging platform

If most of your daily work happens in Feishu, then Feishu/Lark is a very natural way to use Hermes.

The minimum viable integration path

The official documentation recommends this entry command for Feishu/Lark:

hermes gateway setup

After you run it, simply choose Feishu / Lark in the wizard.

The Feishu documentation describes two connection modes:

websocket: recommended
webhook: optional

If Hermes runs on your laptop, workstation, or private server, using websocket first is usually simpler because you do not need to expose a public callback URL.

If you configure it manually, at least know these variables

If you are not using the wizard and are writing the configuration manually, the Feishu documentation lists these core variables:

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=***
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

Two of them deserve special attention:

FEISHU_ALLOWED_USERS: recommended, so not everyone who can reach the bot can use it directly
FEISHU_HOME_CHANNEL: lets you predefine a home chat to receive cron results or default notifications

Why Hermes sometimes does not reply in Feishu group chats

This detail is easy to miss: in Feishu group chats, Hermes does not respond to every message by default.

The official documentation clearly states:

In direct messages, Hermes responds to messages
In group chats, you must explicitly @ the bot before it will process the message

If you want to set a Feishu conversation as the home channel, you can also use this in the chat:

/set-home

Or define it in the configuration ahead of time:

FEISHU_HOME_CHANNEL=oc_xxx

The Hermes commands beginners should remember first

Whether you use Hermes in the CLI or on a messaging platform, remembering the following commands is already enough to get started:

/new or /reset: start a new session
/model: view or switch the model
/retry: retry the previous turn
/undo: undo the previous interaction
/compress: manually compress the context
/help: view help

If you mainly use Hermes on a messaging platform, remember one more:

/sethome or /set-home: set the current chat as the home channel

These commands cover the most common beginner-stage operations: restarting, adjusting, rolling back, checking, and continuing.

Frequently asked questions

Can Windows install Hermes directly?

No. The current official documentation clearly states that native Windows is not supported, and WSL2 is recommended.

What should I do if typing `hermes` does nothing after installation?

It is best to troubleshoot in this order:

Reload your shell first, for example with source ~/.bashrc
Run hermes again
If it is still abnormal, run hermes doctor

Why does the bot not reply in a Feishu group?

Check these three things first:

Whether you @ mentioned Hermes in the group
Whether FEISHU_ALLOWED_USERS restricts the current user
Whether the current group-chat policy allows handling group messages

According to the official Feishu documentation, explicitly using an @mention is required in group-chat scenarios.

Recommended next steps

If you simply want to start using Hermes as quickly as possible, this is the most recommended order:

Run the installation command first
Start with hermes in the local CLI first
Use hermes model and hermes setup to complete the basic configuration
If you want to keep using it in Feishu, then configure hermes gateway setup

If this article is the first part of a series, its best role is not to explain every advanced feature all at once, but to get users in the door first.

The following topics are better split into follow-up articles:

A complete Hermes Feishu integration guide
A guide to common Hermes slash commands
A guide to Hermes gateway configuration and troubleshooting

If you plan to keep creating Hermes content, this article can serve as the starting point for later posts, while you gradually build out the internal link structure.