Hermes Agent

Project Overview

Hermes Agent is an open-source terminal AI agent from Nous Research, bringing powerful tool calling, file read/write, and code execution capabilities to your terminal. Through its built-in Custom Endpoint capability, Hermes can seamlessly connect to any OpenAI-compatible API — including Models Hub — without writing any code or plugins.

• Official homepage: https://hermes-agent.nousresearch.com
• Quickstart: https://hermes-agent.nousresearch.com/docs/getting-started/quickstart
• GitHub: https://github.com/NousResearch/hermes-agent

Hermes Agent is fully open source. You can browse the source, file issues, or contribute in the Hermes Agent GitHub repository. This guide covers installation, configuration, and the complete steps to connect Hermes Agent to Models Hub.

🌟 Key Features

Intelligent agent capabilities

• Tool calling: Native support for tool calling, file read/write, and code execution
• Persistent memory: Supports running as a resident background process with long-term memory
• Skill system: Search and install skill packages via the hermes skills command
• Multiple interfaces: Supports both command-line and TUI (terminal UI) modes

Multi-channel integration

• Message gateway: Manage all channels in one place via hermes gateway
• Multi-platform support: Connect to messaging apps such as Telegram, Discord, Slack, and WhatsApp
• Always online: Runs as a resident background service

Open model ecosystem

• Custom provider: Built-in Custom Endpoint support lets you connect to any OpenAI-compatible API
• Interactive configuration: Complete setup through an interactive menu via the hermes model command — no config file editing required
• Flexible switching: Switch models at any time during a conversation with the /model command

📦 Before You Begin

Information to prepare

• Hermes Agent installed (see the installation steps below)
• A working Models Hub URL (must end with /v1)
• A working Models Hub API Key (generated in the console)
• The name of the model you want to use (e.g., claude-sonnet-4-6, gemini-2.5-flash), which must exactly match the model ID in the Models Hub console

Model context requirement

Hermes Agent requires the model in use to support a context window of at least 64K tokens. When choosing a model, confirm that it meets this requirement; otherwise, you may encounter insufficient-context errors.

🚀 Step 1: Install Hermes Agent

Linux / macOS / WSL2

Run the official one-click install script in your terminal:

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

After installation, reload your terminal environment variables:

source ~/.bashrc

If you use zsh (the default on macOS), run:

source ~/.zshrc

Windows

Note for Windows users

Hermes Agent does not directly support native Windows. You need to install WSL2 (Windows Subsystem for Linux 2) first, then run the Linux/macOS install command above inside a WSL2 terminal.

WSL2 installation guide: https://learn.microsoft.com/windows/wsl/install

Verify the installation

Run the following command to verify that Hermes installed successfully:

hermes --version

If a version number is displayed, the installation succeeded 🎉.

🔧 Step 2: Configure Models Hub (the core step)

This is the most important step in the whole process. Hermes Agent provides an interactive menu so you don't need to write any code or manually edit config files — just follow the prompts to enter your Models Hub URL, Key, and model name.

Run in your terminal:

hermes model

This opens an interactive menu. Use the up/down arrow keys to select an option and press Enter to confirm.

Walkthrough

Configuration steps

1. Select a provider

Use the arrow keys to scroll to Custom Endpoint (or a similarly named "custom endpoint" option) and press Enter to confirm.

2. Enter the Base URL

Enter your Models Hub URL, for example:

https://modelsok.com/v1

⚠️ The URL must end with /v1 — this is the most common source of configuration errors.

3. Enter the API Key

Enter the API Key you generated in the Models Hub console, for example:

sk-xxxxxxxxxxxxxxxx

4. Enter the model name

Enter the model you want to use, for example:

claude-sonnet-4-6

The model name must exactly match the model ID in the Models Hub console, or you'll get a "model not found" error.

5. Confirm and save

Confirm as prompted, and the configuration is complete.

Key configuration reference

✅ Step 3: Verify the connection

Once configured, start Hermes and begin chatting:

hermes

Or use the more modern TUI mode (terminal graphical interface):

hermes --tui

Send any test message, for example:

Hi, tell me what day of the week it is today

If the model returns a normal reply, the connection succeeded 🎉.

View and switch models

During a conversation, enter the following command to view the current model and switch quickly:

/model

You can also run hermes model again at any time to override the previous configuration and re-enter a new URL, Key, or model name.

❓ FAQ

🎯 Next Steps (optional)

After successfully connecting to Models Hub, you can explore more of Hermes Agent's capabilities:

Start the message gateway

Connect Hermes to messaging apps such as Telegram, Discord, and Slack:

hermes gateway setup

Search for and install skills

Hermes has a built-in skill store you can use to extend its capabilities with one click:

hermes skills search <keyword>

View all available commands

hermes --help

Tip

Once connected to Models Hub, all of Hermes Agent's subsequent capabilities (message gateway, skill calls, background residency, etc.) will call your chosen model through Models Hub — there's no need to configure a model provider separately for each feature.