AI Coding Hub

Guide

How to Set Up Hermes Agent (Step-by-Step)

Hermes Agent is Nous Research's self-improving, open-source AI agent. This guide takes you from nothing to a running agent: install it with one command, reload your shell, choose a model provider, run the setup wizard, and verify — with the exact hermes commands from the official repo (read 2026-06-20).

By DK, Editor  ·  Last verified: 2026-06-21  · Hermes Agent v0.17.0 (2026.6.19) — installed & run first-hand 2026-06-21 (binary at ~/.local/bin/hermes, home ~/.hermes, Python 3.11.15). Commands captured from hermes --help and the install summary.  ·  How we test

Before you start

  • A terminal on Linux, macOS, or WSL2 — or PowerShell on native Windows (Termux is supported via a documented manual path)
  • Network access to hermes-agent.nousresearch.com for the installer (it provisions uv, Python 3.11, Node.js, ripgrep, ffmpeg)
  • An account/API key with a model provider — Nous Portal, OpenRouter, OpenAI, NovitaAI, NVIDIA NIM, Hugging Face, or your own endpoint
  • Optional: bot tokens if you plan to use the messaging gateway (Telegram, Discord, Slack, etc.)

Steps

  1. 01

    Install Hermes Agent

    Run the official one-line installer for your platform. On Linux, macOS, and WSL2 use the shell script; on native Windows use PowerShell. The installer is self-contained — it sets up the Python/Node toolchain and the code checkout under your Hermes home directory (~/.hermes, or %LOCALAPPDATA%\hermes on Windows).

    # Linux / macOS / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows (native, PowerShell)
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
  2. 02

    Reload your shell, then start Hermes

    The installer updates your shell profile to put hermes on your PATH. Reload it (or open a new terminal) so the command resolves, then launch Hermes. With no arguments, hermes starts an interactive conversation in the TUI.

    source ~/.bashrc    # or: source ~/.zshrc
hermes              # start chatting interactively
  3. 03

    Choose a model provider

    Hermes is provider-agnostic. Run hermes model to pick a provider and model — options include Nous Portal, OpenRouter (200+ models), OpenAI, NovitaAI, NVIDIA NIM, Hugging Face, and custom endpoints. Switching providers needs no code changes. If you would rather not juggle separate keys for model, web search, image, and TTS, Nous Portal bundles them under one subscription (the Tool Gateway).

    hermes model        # choose your LLM provider and model
  4. 04

    Run the setup wizard (configures everything at once)

    Instead of configuring pieces individually, hermes setup runs a guided wizard that walks through model, tools, and the rest in one pass. To configure against Nous Portal specifically, the README documents hermes setup --portal. You can also view and edit settings with hermes config (or hermes config edit), and choose which tools are enabled with hermes tools.

    hermes setup            # full setup wizard (configure API keys & settings)
hermes setup --portal   # configure with Nous Portal
hermes tools            # choose which tools are enabled
hermes config           # view/edit configuration
hermes config edit      # open the config file in your editor
  5. 05

    (Optional) Start the messaging gateway

    Hermes can run as a single gateway process that reaches you on Telegram, Discord, Slack, WhatsApp, Signal, and the CLI at once — with features like voice-memo transcription and cross-platform continuity. Configure your platform tokens (via the wizard or hermes config), then install the gateway service. This is what lets you 'talk to it from Telegram while it works on a cloud VM.'

    hermes gateway install   # install the gateway service (messaging + cron)
hermes gateway           # manage the gateway
  6. 06

    Verify and maintain your install

    If anything looks off, hermes doctor runs built-in diagnostics across your install, config, and runtime. Keep Hermes current with hermes update, which matches the managed install layout. If you are coming from OpenClaw, hermes claw migrate ports your setup over.

    hermes doctor       # diagnose issues
hermes update       # update to the latest version
hermes claw migrate # migrate from OpenClaw (if applicable)

Troubleshooting

hermes: command not found right after install
Your current shell has not picked up the PATH change the installer wrote to your profile. Run source ~/.bashrc (or source ~/.zshrc), or open a new terminal window, then run hermes again. On native Windows, open a fresh PowerShell session.
The agent runs but has no model / provider configured
Run hermes model to select a provider and model, or run the full hermes setup wizard. You will need an API key (or a Nous Portal subscription, which covers model plus web search, image, and TTS under one account). Use hermes config (or hermes config edit) to adjust settings.
Something is broken and you are not sure what
Run hermes doctor — it diagnoses install, config, and runtime issues and reports what needs attention. If a recent change caused it, hermes update brings you to the latest version, which may include a fix.
The messaging gateway will not connect to Telegram/Discord/etc.
Confirm you configured the correct bot token for each platform (via hermes setup or hermes config) and that the gateway process is running with hermes gateway. Check the provider's bot setup requirements (e.g. enabling the bot, granting permissions). Consult the official docs for per-platform gateway configuration.

Our AI agents

From the team behind AI Coding Hub — agents that pick up where the code ends:

FAQ

How do I install and start Hermes Agent?
Run the one-line installer — curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash on Linux/macOS/WSL2, or iex (irm https://hermes-agent.nousresearch.com/install.ps1) in PowerShell on Windows — then reload your shell (source ~/.bashrc or ~/.zshrc) and run hermes. Confirm the current commands on the official repo before running.
Which models can Hermes Agent use?
Hermes is provider-agnostic. The README lists Nous Portal, OpenRouter (200+ models), NovitaAI, NVIDIA NIM, OpenAI, Hugging Face, and custom endpoints, among others. Switch with hermes model — no code changes. Nous Portal can cover model plus web search, image generation, and TTS under a single subscription.
What does the hermes setup wizard do?
hermes setup runs a guided configuration that sets up everything at once — model/provider, tools, and related settings — instead of configuring each piece separately. hermes setup --portal configures Hermes against Nous Portal specifically. You can still view and edit settings later with hermes config (or hermes config edit).
Do I need a server to run Hermes Agent?
No — you can run it locally from your terminal. But because Hermes is built to run continuously and reach you over chat, many people run it on a small VPS or a serverless backend (it supports backends like Docker, SSH, Modal, and Daytona). That lets it keep working when your laptop is closed. Local install is the simplest way to start.
How do I keep Hermes Agent up to date?
Run hermes update — it updates to the latest version while matching the managed install layout. Because the project moves fast (it is pre-1.0, v0.17.0 as of 2026-06-19), check the official repo periodically for new commands or breaking changes.

Related

Sources: github.com/NousResearch/hermes-agent · hermes-agent.nousresearch.com/docs