Hermes Agent setup and first-use guide

Checked against the official docs on 2026-10-20. This guide is compiled from the Hermes Agent documentation; FollowAgents has not yet run an install test on a current release. Hermes ships often (v0.22.2 when checked), so the linked official pages win wherever they differ.

Hermes Agent is Nous Research's open source personal agent, in the same family as OpenClaw: it runs on your own computer or server, you can talk to it in a terminal or connect it to Telegram, Discord, Slack and more, and it runs commands, researches and handles files for you. Because it executes commands on your machine, settle three things on a first run: where the model comes from and who pays, whether it asks before running commands, and who can give it orders once a chat channel is connected. This guide goes install → model → safety → chat channels.

Still comparing tools? See Hermes Agent's features, fit and source review or OpenClaw vs Hermes Agent.

Step 1: Install

On macOS (Apple Silicon only) and Windows you can download the Hermes Desktop installer from the website, which includes both the CLI and the desktop app. For the CLI only:

Linux, macOS, WSL2:

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

Native Windows PowerShell:

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

The installer brings its own uv, Python and Node.js, so there is no Python to install first; Linux and macOS need only Git, curl and tar. Browser and computer-use tools are installed by default — skip them with --skip-browser and --skip-computer-use (PowerShell: -SkipBrowser, -SkipComputerUse). Code goes to ~/.hermes/hermes-agent/ and your settings and data to ~/.hermes/ (%LOCALAPPDATA%\hermes\ on Windows).

Reload your shell (for example source ~/.zshrc); if anything is off, run hermes doctor, which says what is missing and how to fix it. See the official installation docs.

Step 2: Connect a model

Run the setup wizard:

hermes setup

It offers three paths:

Switch models any time with hermes model, or set values directly:

hermes config set OPENROUTER_API_KEY sk-or-...
hermes config set model anthropic/claude-opus-4.6

Mind the context window: the docs require at least 64K tokens, and Hermes refuses smaller ones at startup — the usual snag with small local models. Secrets live in ~/.hermes/.env and other settings in ~/.hermes/config.yaml; hermes config set writes each to the right file. See the official quickstart and the Nous Portal docs.

Then start chatting:

hermes --tui

hermes --tui is the recommended interface, hermes the classic CLI, and hermes -c resumes the last session.

Step 3: Know what it can do on your machine (read this)

By default Hermes runs commands directly on your machine with no isolation (terminal.backend defaults to local). Its safeguard is command approval, per the official security docs:

• approvals.mode defaults to smart: another model rates the risk, auto-approves low-risk commands, auto-denies dangerous ones and asks you only when unsure.
• To be asked about every dangerous command, switch to manual:

hermes config set approvals.mode manual

• An approval prompt left unanswered for 300 seconds is denied, and commands such as rm -rf / or fork bombs are refused under any setting.
• --yolo, /yolo or approvals.mode: off skip every approval. Don't do that on a machine holding anything you care about.

Safer still, run its commands in a container (Docker must be installed):

hermes config set terminal.backend docker

Step 4: Connect chat apps

Make sure terminal chat works first, then:

hermes gateway setup     # interactive platform setup
hermes gateway           # start the gateway
hermes gateway status    # check its state

Hermes supports 20+ platforms including Telegram, Discord, Slack, WhatsApp and Microsoft Teams. Once connected, who may give it orders is the setting that matters:

• Allowlist user IDs in ~/.hermes/.env, for example TELEGRAM_ALLOWED_USERS=123456789; GATEWAY_ALLOWED_USERS applies to every platform.
• With no allowlist configured, everyone is denied. Unknown DMs get a pairing code, which you approve with hermes pairing approve <platform> <code>.
• The docs advise against GATEWAY_ALLOW_ALL_USERS=true in production — it hands your machine to anyone in the channel.

See the official messaging docs.

Maintenance

• Update: hermes update
• Troubleshooting order (from the docs): hermes doctor → hermes model → hermes setup → hermes sessions list → hermes --continue → hermes gateway status

On Windows

Hermes installs natively from PowerShell or inside WSL2; the docs don't prefer one. A native install keeps its data in %LOCALAPPDATA%\hermes\; in WSL2 it is ~/.hermes/ as on Linux. They are separate installs with separate settings. The Hermes Desktop installer is the third option.

FAQ

Is Hermes Agent free? The software is free and open source (MIT, source at NousResearch/hermes-agent). Models and tools cost money: a Nous Portal subscription or your own API keys.

How is it different from OpenClaw? Both are self-hosted personal agents that plug into chat apps. See OpenClaw vs Hermes Agent and the personal agents ranking.

Can I use the Hermes 4 model? You can, but the docs note Hermes 4 is tuned for chat rather than tool calling and advise against it as the main model inside Hermes Agent.

What plugins and companion projects exist? Web UIs, desktop clients, skill packs and more in the directory are listed under the Hermes Agent profile's ecosystem section.