Hermes Agent setup: install, model, gateway and MCP

Updated 8 min read

Hermes Agent setup comes down to four steps: install it with one command (or the desktop app), choose a model provider with hermes model, check that a plain chat works, then run the gateway so you can reach it from Telegram or Slack. Profiles, skills, MCP servers and cron jobs come after that, one at a time. This guide follows the current Nous Research docs and the hermes CLI (v0.42.5) that we run on a Mac.

What do you need before you install Hermes Agent?

  • A supported system. macOS on Apple Silicon, Linux, WSL2, native Windows, or Android through Termux. The docs say macOS on Intel is not supported.
  • Git, curl, tar and SHA-256 tools for the command-line installer. The script fetches its own pinned Python and Node.js.
  • A model. A provider account (Nous Portal, OpenRouter, Anthropic and many others) or a local model with a context window of at least 64,000 tokens. Hermes rejects smaller models at startup.
  • A bot token, later, for each chat app you want to use.

How do I install Hermes Agent?

There are two routes. The desktop package (a DMG on macOS, an .appinstaller on Windows, both from the Hermes website) bundles the agent, Python and its dependencies. For a command-line install on Linux, macOS or WSL2:

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

On native Windows, in PowerShell:

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

The script clones the source, bootstraps uv, and installs pinned Python, Node.js, ripgrep and FFmpeg, plus browser and computer-use tools (it takes --skip-browser and --skip-computer-use if you do not want them). On an interactive run it goes straight on to setup and gateway configuration. Code lands in ~/.hermes/hermes-agent/, the launcher in ~/.local/bin/hermes, and your data in ~/.hermes/.

Reload your shell and check the install:

source ~/.zshrc      # or ~/.bashrc
hermes --version

Ours prints this (home directory shortened to ~):

Hermes Agent v0.42.5 (2026.7.7.2) · upstream 8aa1589d
Install directory: ~/.hermes/hermes-agent
Install method: git
Python: 3.11.16
OpenAI SDK: 2.24.0
Up to date

hermes --help in this version lists 55 command names (a few are aliases). The ones that matter for setup are setup, model, chat, gateway, profile, skills, mcp, cron, memory, tools and doctor. If the shell says hermes: command not found, reload it or check that ~/.local/bin is on your PATH.

How do I choose a model provider?

Run the picker, or the full wizard:

hermes model            # choose provider and default model
hermes setup            # full wizard
hermes setup --portal   # one-shot Nous Portal login, model and Tool Gateway
hermes setup model      # rerun one section: model, tts, terminal, gateway, tools or agent

On a fresh install, hermes setup offers three modes. Quick Setup logs you in to Nous Portal with OAuth and turns on its Tool Gateway (web search, image generation, text to speech, a cloud browser). Full Setup walks through every provider and tool with your own keys. Blank Slate starts with only a provider, file tools and the terminal, and leaves everything else off until you enable it.

The provider table in the quickstart covers Nous Portal, OpenRouter, Anthropic, OpenAI Codex (a ChatGPT subscription), Google AI Studio, GitHub Copilot, AWS Bedrock, DeepSeek, LM Studio and more than 30 others, plus any OpenAI-compatible endpoint such as vLLM or Ollama. For a local model, set its context to at least 64K (--ctx-size 65536 in llama.cpp, from the docs).

Hermes keeps secrets apart from settings: API keys go in ~/.hermes/.env and everything else in ~/.hermes/config.yaml. hermes config set writes each value to the right file:

hermes config set terminal.backend docker   # run the agent's commands in a container

How do I run my first chat?

hermes          # classic terminal interface
hermes --tui    # newer terminal UI with overlays and mouse support
hermes -c       # resume the most recent session

Ask something you can check, such as “Summarize this repo in 5 bullets and tell me what the main entrypoint is.” The docs list what success looks like: the banner shows your model, Hermes replies without an error, it can use a tool, and the conversation carries on past one turn. Their rule of thumb is worth keeping: if a normal chat does not work, do not add features yet. hermes doctor reports what is missing.

Hermes also loads project instruction files into every conversation: AGENTS.md, CLAUDE.md, .hermes.md and .cursorrules. If you already keep an AGENTS.md for other coding agents, Hermes will read it too.

How do I connect Hermes Agent to Telegram or Slack?

The gateway is one background process that connects to every platform you configure (Telegram, Discord, Slack, WhatsApp, Signal, Email, Matrix, Microsoft Teams and more than 20 in all), keeps a session per chat, and runs the cron scheduler.

hermes gateway setup     # pick platforms and paste tokens
hermes gateway           # run in the foreground to test
hermes gateway install   # launchd service on macOS, user service on Linux
hermes gateway status

Telegram. Message @BotFather, send /newbot, and copy the token. Get your numeric user ID from @userinfobot. The wizard writes both to .env, or you can add them yourself:

TELEGRAM_BOT_TOKEN=<token from BotFather>
TELEGRAM_ALLOWED_USERS=123456789

Slack. Hermes uses Socket Mode, so your machine needs no public URL. hermes slack manifest --agent-view --write generates an app manifest; paste it into Create New App, From an app manifest at api.slack.com/apps, then install the app. You need a bot token (xoxb-) and an app-level token (xapp-). The docs name the most missed scopes: without channels:history and groups:history the bot only answers in DMs.

The gateway denies everyone who is not on an allowlist or paired, which is the right default for a bot that can run terminal commands. To let someone in without editing .env, they DM the bot, get a code, and you run hermes pairing approve telegram <code>. The docs advise against GATEWAY_ALLOW_ALL_USERS=true for this reason.

How do I run more than one Hermes agent?

With profiles. Each profile is a separate Hermes home with its own config, .env, memory, sessions, skills, cron jobs and gateway. From hermes profile --help:

usage: hermes profile [-h]
       {list,use,create,delete,describe,show,alias,rename,export,import,install,update,info}
hermes profile create coder   # creates the profile and a "coder" command
coder setup                   # its own model and keys
coder chat
coder gateway start           # its own bot, if you want one

--clone copies config.yaml, .env, SOUL.md and skills from the active profile, and hermes gateway list shows every profile with its gateway status. The docs are firm on one point: never point two running agents at the same profile, because both write memory and load each other’s writes. We run several profiles on one Mac from a single install, each with its own model, memory and bot. The full walkthrough is in the Hermes Agent profiles guide.

How do I add skills?

Skills are markdown documents Hermes loads when a task needs them, and it writes new ones from its own experience. To add skills from registries such as skills.sh, GitHub and ClawHub:

hermes skills browse
hermes skills search <topic>
hermes skills install openai/skills/skill-creator
hermes skills list

hermes skills install also takes a direct URL to a SKILL.md. How skills load, and how to share them between profiles, is in the Hermes Agent skills guide.

How do I add an MCP server to Hermes Agent?

MCP support ships with the standard install. From hermes mcp add --help:

usage: hermes mcp add [-h] [--url URL] [--command MCP_COMMAND] [--args ...]
                      [--auth {oauth,header}] [--preset PRESET]
                      [--connect-timeout CONNECT_TIMEOUT] [--env [ENV ...]]
                      name

A remote server and a check:

hermes mcp add myserver --url https://example.com/mcp --auth oauth
hermes mcp test myserver
hermes mcp list

A local stdio server can go straight into config.yaml, as in the docs:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

Hermes also ships a catalog of servers Nous has reviewed: hermes mcp catalog lists them and hermes mcp install deepwiki installs one. Headers can reference ${VAR} values from .env, so keys stay out of config.yaml. In a running chat, /reload-mcp picks up changes.

What does Hermes Agent remember?

Each profile keeps two short memory files, MEMORY.md (the agent’s notes) and USER.md (your preferences), plus a searchable record of past sessions. hermes memory configures an external provider such as Honcho, Mem0, Hindsight or Supermemory. Limits and details are in the Hermes Agent memory guide.

How do I schedule a cron job?

hermes cron create "every 2h" "Check server status"
hermes cron create "0 9 * * *" "Send me a short morning briefing" --deliver telegram
hermes cron list
hermes cron status

Schedules take 30m, every 2h or a cron expression, and --skill attaches a skill. In chat, /cron add "every 2h" "Check server status" does the same, or you can ask Hermes in plain words. The scheduler runs inside the gateway and ticks every 60 seconds, so install the gateway as a service if jobs should fire while your terminal is closed.

Share what Hermes learns with your other agents

Hermes memory belongs to one profile and is kept short on purpose. If you also run Claude Code, Codex, Cursor or a second Hermes profile, none of them see what this one learned. Dexio is a hosted wiki that all of them read and write over MCP, and you see what your agents know as a graph of linked pages at app.dexio.wiki. It is free for one person.

Connecting takes one message to Hermes: ask it to follow https://dexio.wiki/agents.md. It runs a browser sign-in, saves the API key to the profile’s .env, and adds the server with hermes mcp add. The steps and checks are in the memory guide.

Hermes Agent setup checklist

  • hermes --version prints a version and hermes doctor is clean.
  • hermes model set to a model with at least 64K context.
  • One multi-turn chat works and hermes -c resumes it.
  • Gateway configured, allowlist or pairing in place, hermes gateway install done.
  • One profile per agent, never two agents on one home.
  • Skills you need installed; hermes skills list shows them.
  • MCP servers pass hermes mcp test <name>.
  • Cron jobs listed in hermes cron list, delivering where you expect.

FAQ

Is Hermes Agent free? The agent is open source under the MIT license. You pay your model provider, or nothing for a local model.

Does Hermes Agent run on an Intel Mac? Not according to the installation docs: the macOS installer is Apple Silicon only, and macOS on Intel is listed as unsupported.

Should I pick Hermes Agent or OpenClaw? They differ in how they run several agents and how they learn. See Hermes Agent vs OpenClaw and the OpenClaw setup guide. hermes claw holds tools for migrating from OpenClaw.

Sources

Ask a question

Ask anything about Dexio.

About
We reply by email.