How to Install Hermes Agent: Beginner Setup Guide

Hermes Agent is an open-source AI agent from Nous Research that runs from your terminal, connects to different model providers, remembers useful context across sessions, and can be extended with tools, skills, messaging gateways, and automation. This guide helps you to know how to install Hermes. You do not need to manually install Python or Node.js for the standard installer on macOS or Windows because the official installer handles the main dependencies for you.

Before You Install Hermes Agent

Hermes Agent is terminal-first software, so you will install it from a command line. Choose the section that matches your computer:

• macOS: open Terminal from Applications > Utilities > Terminal, or press Command + Space and search for "Terminal."

• Windows: install WSL2 first, open your Linux distribution terminal, then follow the Linux command.

You also need Git. Check whether Git is installed:

Expected output:

If you see git: command not found, install Git first:

If you do not have Homebrew on macOS, install Git from Apple Command Line Tools by running:

Step 1: Install Hermes Agent on macOS or Windows

In your terminal, copy and paste the official installer command:

The installer downloads Hermes Agent, prepares its Python environment, installs required dependencies, and adds the hermes command to your shell path. On a normal user install, Hermes data is stored under ~/.hermes/.

When the command finishes, reload your shell:

If you use Zsh, which is common on macOS, run:

Expected result:

Now confirm that the Hermes Agent command is available:

Expected result:

The exact version number may change as Hermes Agent is updated.

Step 2: Configure Your Model Provider

Hermes Agent needs a model provider before it can answer or use tools. The easiest beginner setup is interactive:

The wizard lets you choose a provider such as Kimi/Moonshot. Do not configure routing, fallback, gateway, or cron until a basic chat works.

Select the default model. kimi-k2.6 is Kimi's most advanced model so far.

If you already know the value you want to set, you can use hermes config set. For example:

If you don't have an api-key, Kimi could be a cool choice.

Step 1: Activate your Kimi API

Before using the Kimi API with the Hermes Agent, activate your Kimi API Key in the Kimi Platform. We recommend $20+ to unlock Tier 2 access, which reduces latency and supports more stable performance for complex, multi-step tasks

Step 2: Create your Kimi API Key

Go to the API Keys section in Kimi Platform and click Create API Key. Remember to copy your API key and store it securely. Because the key is only shown once at creation.

Step 3: Enter your API key

Paste your Kimi API key and connect the Hermes Agent.

Step 3: Start Hermes Agent

Once the model is configured, start the classic CLI:

Or try the newer terminal UI:

You should see a welcome screen or prompt that shows your selected provider/model. Test it with a simple request:

Success looks like this:

If Hermes Agent opens but replies with model or authentication errors, run:

Then choose your provider again and verify the API key or OAuth login.

Step 4: Turn Hermes Agent into a Bot

Like OpenClaw, Hermes Agent can also act as a bot and connect to your chat apps:

After setup, check gateway status:

Use the gateway only after your model provider works in the terminal. If the CLI cannot complete a basic chat, the bot will usually fail for the same reason.

Common Hermes Agent Installation Problems

hermes: command not found

Cause: your terminal has not reloaded the PATH change yet.

Fix:

Or:

Then try:

git: command not found

Cause: Git is missing.

Fix on Ubuntu, Debian, or WSL2:

Fix on macOS with Homebrew:

API Key Not Set

Cause: Hermes Agent is installed, but no provider key or login is configured.

Fix:

Or set a key manually:

hermes doctor Reports Missing or Stale Config

Cause: your config file may be incomplete after an update.

Fix:

Custom Endpoint Connects but Gives Bad Replies

Cause: the base URL, model name, or context length is wrong.

Fix: test the endpoint in a separate client first, confirm it is OpenAI-compatible, and make sure the model supports at least 64K context for normal Hermes Agent workflows.

Quick Command Reference

Conclusion

The easiest way to install Hermes Agent is to use the official one-line installer, reload your shell, run hermes model, and verify the setup with one real chat plus hermes doctor. Keep your first setup simple: one machine, one provider, one working conversation. Once the base Hermes Agent assistant is stable, you can safely build on it with Docker isolation, gateway bots, skills, scheduled automations, and custom model providers.