ABS guide draft · MiniMax M3

How to Set Up Hermes Agent — MiniMax M3 Draft

A second ABS guide draft generated with MiniMax M3 for comparison against the first Hermes Agent setup guide.

Review copy · Updated July 10, 2026

How to Set Up Hermes Agent

Hermes Agent is a terminal-native AI agent from Nous Research. It runs in your shell, uses tools when you ask it to, and can be wired into messaging platforms so you can talk to it from Telegram or Discord instead of sitting at a terminal. This guide is the manual-first path: install it, pick a model, get a clean chat working, then layer on tools, memory, skills, and the gateway.

The goal is a working setup in roughly ten minutes that survives real use — not a feature tour. If something breaks, the verification checklist and failure table at the end are the fastest way back.

What Hermes Agent Is

Hermes Agent is a self-improving coding and task agent. The pieces that matter for setup:

A full TUI/CLI for interactive chat (hermes, hermes chat).
A tool registry organized into toolsets (web, terminal, memory, skills, etc.).
A skills system — on-demand SKILL.md documents that teach it specific tasks.
Persistent memory (MEMORY.md, USER.md) plus session search.
A messaging gateway that runs as a separate process and connects to Telegram, Discord, Slack, and other platforms.
A plugin system for adding your own tools without forking the core.

You do not need all of this on day one. Start with the CLI and one provider.

Before You Start

Decide three things in advance. They shape every step that follows.

Where it runs. Linux, macOS, WSL2, Termux (Android), or native Windows. The installer is a one-liner on every supported platform. Native Windows is fully supported without WSL; if you prefer WSL2, the Linux command works there too. Termux uses a curated [termux] extra because the full extras pull Android-incompatible voice dependencies.
Which provider. The default path is OpenRouter, which gives you access to many models with one API key. Nous Portal is a one-shot alternative — one subscription covers 300+ models and the Tool Gateway (web search, image generation, TTS, cloud browser) without per-tool keys. You can also point Hermes at any OpenAI-compatible endpoint (local Ollama, LM Studio, a self-hosted proxy) or use Anthropic, Google, OpenAI Codex, xAI, AWS Bedrock, and others directly.
What “done” looks like. For a first setup, “done” means: hermes chat -q "Hello" returns a sensible reply from the model you picked. Nothing else. Gateway, cron, skills, voice, and plugins come after that.

Pick the provider before you run hermes model so you can paste the key straight in.

Fast Setup Path

Run this end-to-end on Linux, macOS, WSL2, or Termux:

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

On native Windows, run in PowerShell:

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

The installer handles Python 3.11, Node.js, ripgrep, ffmpeg, the repo clone, the virtual environment, and the global hermes command. On Windows, it also provisions a portable Git Bash (MinGit) so shell commands work without touching any system Git.

After the installer finishes, reload your shell and verify the binary is on PATH:

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

hermes doctor is the first diagnostic you should run after any install or config change. It checks dependencies and flags missing or stale config. If doctor is clean, move on.

Configure Model and Provider

The provider is the single most important setup step. Use the interactive picker:

hermes model

This walks you through provider selection, model choice, and credential entry. Pick OpenRouter for the broadest model access with one key, or pick Nous Portal if you want the one-subscription path that also turns on the Tool Gateway.

If you want the fastest possible setup and you have a Nous Portal subscription, run:

hermes setup --portal

That logs you in via OAuth, picks a Nous model, sets Nous as the provider, and opts into the Tool Gateway in one command. Skip the per-tool key juggling.

If you are pointing at a custom OpenAI-compatible endpoint (local model server, LM Studio, a proxy), hermes model lets you configure the base URL, model name, and context length. Verify the endpoint in a separate client first — if your custom endpoint “works” but returns garbage, the usual culprits are a wrong base URL, a model name the server doesn’t actually serve, or a non-OpenAI-compatible API path.

To reconfigure later, you do not have to re-run the whole wizard. Each section is its own command:

hermes setup model       # change provider/model only
hermes setup gateway     # change messaging platforms only
hermes setup tools       # change tool gating only

You can also edit values directly:

hermes config show
hermes config set <key> <value>
hermes config path       # where config.yaml lives

Enable Only Useful Tools

Hermes ships with a broad tool registry. Enabling everything is tempting and almost always wrong — more enabled tools means more chances for the model to pick the wrong one, and some tools (browser automation, computer use) carry real risk if miscalled.

Start with the minimum that matches your real work, then add as you hit specific needs:

terminal, file — for coding and ops tasks. Usually on by default.
web, search — for current information and link fetches.
memory, session_search — for cross-session recall. Enable memory once you’re ready for the agent to remember things.
skills — enables loading SKILL.md content on demand. Useful, low-risk.
browser, computer_use, image_gen, tts — opt in when you actually need them.
cronjob — opt in only when you start scheduling. (Cron is intentionally not covered in this manual-first guide.)

Configure tools per platform:

hermes tools              # interactive per-platform config UI
hermes tools list         # see what's enabled where
hermes tools enable web,skills
hermes tools disable browser

Toolsets in hermes chat --toolsets "web,terminal" are scoped to a single invocation and are a good way to test whether a toolset helps before turning it on globally.

Memory vs Skills

These two features overlap in casual descriptions but solve different problems.

Memory is the agent’s persistent notes about you and what it has learned. It writes to MEMORY.md and USER.md in your Hermes home directory. Memory is short by design — the default caps are tuned so the agent can read its full memory on every turn without burning the context window.

If you want to review writes before they land, toggle write approval:

hermes setup memory
# or edit config.yaml:
# memory.write_approval: true

With write approval on, interactive sessions prompt inline; messaging sessions and the background review queue the write for /memory pending → /memory approve <id> / /memory reject <id>. You can flip this at runtime with /memory approval on|off.

Skills are on-demand instruction documents. Each skill is a SKILL.md file with a name, a short description, and a procedure. The agent reads the descriptions cheaply and only loads the full skill when a task actually calls for it, so adding skills does not bloat every request.

Hermes ships with a catalog of bundled skills in ~/.hermes/skills/. You can browse and install more from the Skills Hub:

hermes skills browse                      # list everything available
hermes skills search kubernetes           # find skills by keyword
hermes skills install openai/skills/k8s   # install one (runs a security scan first)

Installed skills become slash commands. Run them directly or let Hermes pick the right one during normal conversation.

Rule of thumb: memory is for “remember who I am and what I prefer,” skills are for “here’s how to do this specific task.”

Messaging and the Gateway, After the CLI Works

The gateway is a separate process that connects Hermes to Telegram, Discord, Slack, WhatsApp, Signal, and other platforms. It is not the CLI. If the CLI cannot complete a normal chat, the gateway will not save you — fix the base setup first.

When the CLI is healthy, configure a platform:

hermes gateway setup

Then run the gateway. The right command depends on your platform:

hermes gateway run        # foreground (recommended for WSL, Docker, Termux)
hermes gateway install    # install as a systemd/launchd background service
hermes gateway start      # start the installed background service
hermes gateway status     # see what's running
hermes gateway list       # all profiles and their gateway status

Use hermes gateway setup again any time you need to change platforms, tokens, or allowlists. Common failures — bot token wrong, allowlist missing, platform incomplete — show up here, not in the agent itself.

One operational note worth knowing up front: the gateway is the process running the agent session when you talk to it from a messaging platform. Restarting the gateway from inside an agent session will drop your turn. Use a separate shell, or restart from your platform client.

Verification Checklist

Run these in order. Each one confirms a layer before you build on it.

hermes --version — binary present and on PATH.
hermes doctor — dependencies and config clean.
hermes chat -q "Reply with the word OK." — provider auth works, model responds, no tool calls needed.
hermes tools list — confirm the toolsets you intended are actually enabled.
hermes chat -q "What's in the current directory?" --toolsets terminal — terminal tool works against your real shell.
hermes chat -q "Summarize https://example.com" --toolsets web — web tool works (only if you enabled it).
hermes sessions list — sessions are being persisted (you will need this for --continue and --resume).
hermes gateway status — if you set up the gateway, it reports the platforms you configured as connected.
hermes chat -c — resuming the last session works.

If any step fails, stop and fix it before moving on. Layering on more features on a broken base is how setups drift from “almost working” to “mysteriously broken.”

Common Failures and Fixes

Symptom	Likely cause	Fix
Hermes opens but gives empty or broken replies	Provider auth or model selection is wrong	Re-run `hermes model`; confirm provider, model, and key
Custom endpoint “works” but returns garbage	Wrong base URL, wrong model name, or non-OpenAI-compatible API	Verify the endpoint in a separate client first
Gateway starts but nobody can message it	Bot token, allowlist, or platform setup is incomplete	Re-run `hermes gateway setup`; check `hermes gateway status`
`hermes --continue` can’t find an old session	Switched profiles or the session never saved	`hermes sessions list`; confirm you’re in the right profile
Model unavailable or odd fallback behavior	Provider routing or fallback settings too aggressive	Keep routing off until the base provider is stable
`hermes doctor` flags config problems	Config values missing or stale	Fix config; retest a plain chat before adding features
Antivirus quarantines `uv.exe` on Windows	False positive on the bundled Rust package manager	Verify the binary against the Astral release (attestation + hash match), then whitelist the Hermes bin folder — not the file hash
Terminal backend does nothing	Wrong backend selected (Docker, SSH, Singularity)	`hermes setup terminal` and pick `local` for a default install

For deeper breakage, the recovery sequence is:

hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
hermes gateway status

That sequence covers the cases that waste the most setup time.

How to Improve Over Time

A setup that survives a week is more valuable than one that demos well for ten minutes. A few habits that pay off:

Add skills on demand, not up front. When a task comes up twice, look for a skill; install it; let the agent use it.
Review memory periodically. With write_approval: true, you get a natural review queue. Without it, skim MEMORY.md and USER.md occasionally and prune stale notes.
Use per-invocation toolsets for experiments. --toolsets "web" keeps a risky tool out of your default chat.
Keep AGENTS.md in projects you work in often. It injects project context automatically, the same way .cursorrules and .hermes.md do.
Treat the gateway as production infrastructure once it’s serving real users. Background service install, status checks, and a separate shell for restarts.

When something feels off, run hermes doctor before you trust any other signal.

When Not to Use It

Hermes Agent is built for people who live in a terminal and want their AI there too. It is less appropriate when:

You want a polished GUI chat. Use the Hermes Desktop installer if you want the desktop app, but the core experience is the TUI.
You need a single click-and-forget hosted assistant. There is no managed Hermes cloud — you run it.
Your tasks are pure chat with no tool use. A lighter client will be faster and cheaper.
You cannot tolerate a tool-calling agent running with shell access. Hermes supports a local terminal backend, which means the agent runs commands as you. Use Docker, SSH, or another sandboxed backend if that is a problem, and enable dangerous-command approval rather than --yolo.

If any of those describes you, Hermes is not the wrong tool — but it is the wrong tool for that job.

Sources and Accuracy Note

All commands and behavior described here are grounded in the official Hermes Agent documentation and the public README at the linked sources above. The command surface (hermes, hermes chat, hermes setup, hermes model, hermes tools, hermes gateway, hermes doctor, hermes config) was cross-checked against the current hermes --help output on a working install.

A few claims are intentionally conditional because they depend on what you have enabled or which provider you picked:

Specific tool availability assumes you have turned the relevant toolset on. The default set is intentionally minimal.
Gateway platform availability depends on which messaging platform you configure; the gateway supports many, but you only see the ones you set up.
The Tool Gateway (web search, image generation, TTS, cloud browser without per-tool keys) is gated on a paid Nous Portal subscription.
Custom endpoint behavior depends on the endpoint actually being OpenAI-compatible and on the model name the server serves.

Stale install details — exact version numbers, internal paths, internal cron identifiers, and the contents of any one operator’s ~/.hermes/ — were deliberately excluded. Run hermes --version and hermes doctor on your own machine for current state, and consult the official docs (linked above) for anything that changes between releases.