Hermes Agent — raw research

Checked: 2026-11-14.

Scope: official Nous Research site, Hermes docs, and the GitHub repo/API. Figures below are copied from pages opened on that date. Where a page disagreed with another page, both wordings are kept. Where a number was not on a page that was opened, it is marked UNVERIFIED.

Primary URLs:

• Product site: https://hermes-agent.nousresearch.com/
• Docs: https://hermes-agent.nousresearch.com/docs/
• Repo: https://github.com/NousResearch/hermes-agent
• Repo API (stars, license): https://api.github.com/repos/NousResearch/hermes-agent
• Releases API: https://api.github.com/repos/NousResearch/hermes-agent/releases?per_page=5
• README (raw): https://raw.githubusercontent.com/NousResearch/hermes-agent/main/README.md

1. What it is, who makes it, license, release, stars

What it is. The GitHub description is "The agent that grows with you." The README (main, fetched 2026-11-14) calls it:

The self-improving AI agent built by Nous Research. It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions.

The same README says it runs on a VPS, a GPU cluster, or serverless infrastructure, and that you can talk to it from Telegram while it works on a cloud VM. It is a terminal agent plus a desktop app plus a messaging gateway, not a single chat window.

Maker. Nous Research. README links the org to https://nousresearch.com. GitHub owner is the organization NousResearch.

License. MIT.

• GitHub API license.spdx_id: MIT (fetched 2026-11-14).
• README ending: "MIT — see LICENSE. Built by Nous Research."
• Product FAQ, https://hermes-agent.nousresearch.com/ : "Hermes Agent is free and open source under the MIT license. Model providers and optional hosted services have their own pricing."

The software license does not include model or cloud bills.

Repo created. GitHub API created_at: 2025-07-22T22:22:28Z.

Stars (point in time). GitHub API stargazers_count: 263308. Same response: forks_count 59343, open_issues_count 53315. API updated_at: 2026-11-14T14:50:53Z. Stars move; this is the count returned by that API call on 2026-11-14, not a rounded marketing number. open_issues_count is the API field only. This note does not split issues from pull requests.

Latest release — stable vs canary. Do not treat the newest tag as the version a normal install gets.

From https://api.github.com/repos/NousResearch/hermes-agent/releases?per_page=5 on 2026-11-14:

The two dates are both on official pages. The API timestamp for stable v0.23.1 is 2026-11-10 01:42:15 UTC. The human-written notes say November 9, 2026. This note does not pick one as "more true."

Installer behavior, https://hermes-agent.nousresearch.com/docs/getting-started/installation :

A new install lands on the latest stable release, the channel hermes update follows from then on (see Updating). To install the tip of main instead, pass --channel main on POSIX or -Channel main on Windows.

So a default install on 2026-11-14 is documented as stable v0.23.1, not the same-day canary. The canary is a pre-release on the GitHub releases list.

v0.23.1 notes (https://github.com/NousResearch/hermes-agent/releases) describe it as a patch that rolls up the pull requests since v0.23.0 into the GitHub release, Microsoft Store app, Docker, and Hermes Cloud. They also say full curated notes for that window ship later with v0.24.0. Previous stable tag in the same API page: v0.23.0, published 2026-11-05T21:32:33Z, name "Hermes Agent v0.23.0 — The Hearth Release."

Language. API language: Python. Desktop app is also Electron (see Desktop section).

2. Exact install — Windows 11 and macOS

Source: installation guide https://hermes-agent.nousresearch.com/docs/getting-started/installation and platform matrix https://hermes-agent.nousresearch.com/docs/getting-started/platform-support , plus the README and the product homepage. All fetched 2026-11-14.

There are two families of install: a prebuilt desktop package, and a terminal/source installer. They can share one data directory. Desktop docs say the packaged app uses HERMES_HOME (~/.hermes, or %LOCALAPPDATA%\hermes on Windows), "the same layout a CLI install uses."

OS support, including conflicts

Platform matrix, Tier 1:

Installation guide, separate from the homepage:

The macOS installer is Apple Silicon only. macOS on x86 (Intel) processors is not a supported platform.

Platform-support page, Intel Macs: the Hermes-Setup.dmg bootstrap installer is Apple Silicon only and reports "not supported on this Mac." "Intel Macs can install the CLI and run hermes desktop." Intel x86_64 macOS desktop bundles are listed under Unsupported ("none are built"). brew install hermes-agent and pip install hermes-agent are also unsupported.

Homepage https://hermes-agent.nousresearch.com/ labels the desktop cards macOS 12+ and Windows 10/11, with a Microsoft Store button and "Download .exe instead."

v0.23.0 release notes (5 Nov 2026, still on the releases page) say, and the fetched text is cut off mid-sentence:

Desktop needs macOS 13+ and 64-bit Windows. The app moved to Electron 44, which...

So published pages disagree: homepage macOS 12+ vs v0.23.0 notes macOS 13+; homepage Windows 10/11 vs platform matrix "MSIX requires Windows 11 22H2 or later." The CLI on Windows 10 is still listed as Tier 1 via install.ps1. Which exact Windows 11 build a Store install accepts was not opened as a Store listing. UNVERIFIED beyond the MSIX sentence above.

Desktop guide https://hermes-agent.nousresearch.com/docs/user-guide/desktop : "It runs on macOS (Apple Silicon), Windows, and Linux — see Platform Support for the full matrix." Linux desktop packages are not in the release workflow: "Linux desktop packaging is disabled in the release workflow."

macOS desktop (recommended path on the install page)

From the installation guide:

• Download the package from the Hermes website (https://hermes-agent.nousresearch.com/).
• Open the DMG, then copy Hermes.app to Applications.
• The ZIP artifact carries the signed app used by the automatic updater.
• Bundled packages contain the agent, Python, supported dependencies, and prebuilt interfaces. First launch does not build that base runtime. Provider access and optional integrations can still require network access.
• A Hermes-Setup bootstrap installer is a different thing: it downloads a source installation and builds the desktop app.
• There is no separate remote-only Desktop download. To use Desktop against a Hermes backend on another machine, install a desktop package and connect it from Settings → Gateways.

No terminal command is the documented way to install the prebuilt DMG. The site shows a "Download desktop app" control; the exact CDN filename behind that button was not captured. UNVERIFIED as a shell command.

macOS terminal

Installation guide and README, Linux / macOS / WSL2:

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

After installation, the same pages say:

source ~/.bashrc    # reload shell (or: source ~/.zshrc)
hermes              # start chatting!

If Desktop was not installed with the script, the install guide says to run:

hermes desktop

That command, per the Desktop guide, "installs workspace Node dependencies, builds the current OS's unpacked Electron app, then launches that packaged artifact." That is a source build, not the prebuilt DMG. Prebuilt installers are the path that "does not build that base runtime."

POSIX layout from the install guide: code in ~/.hermes/hermes-agent/, CLI wrapper ~/.local/bin/hermes, data ~/.hermes/.

Prerequisites for the POSIX script: Git, curl, tar, and SHA-256 utilities. Current first-party installations run on Python 3.14, provided by the installer's PM tool store, not an arbitrary system Python. The script always downloads its own pinned uv.

Windows desktop

Installation guide:

• Download from the Hermes website.
• Open the .appinstaller download with Windows App Installer. It installs the signed MSIX bundle and records its update source.
• Microsoft Store packages have separate Store ownership.
• MSIX requires Windows 11 22H2 or later (platform matrix).

Homepage also offers Microsoft Store and "Download .exe instead" under a Windows 10/11 heading. v0.23.1 update notes distinguish:

• Microsoft Store app: updates through the Store.
• Desktop app installed from the installer (.exe / .dmg): "no change in this release; it updates with the next bundled release."
• CLI: hermes update, or re-run the installer one-liner.

Canary release notes list Windows downloads as MSIX for x86 64-bit and ARM64. Whether the homepage ".exe" is a wrapper around that MSIX was not opened as a file listing. UNVERIFIED.

Windows terminal (native PowerShell)

README and installation guide. README says native Windows runs Hermes without WSL: CLI, gateway, TUI, and tools. WSL2 can use the bash one-liner instead.

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

README on what that script pulls in: Python 3.14, Node.js, npm, pnpm, ripgrep, FFmpeg, and Python dependencies, delegated to PM. If Git is absent, it stages a verified Git for Windows archive in Hermes' tool store and does not replace system Git.

Native Windows install location: %LOCALAPPDATA%\hermes. Code: %LOCALAPPDATA%\hermes\hermes-agent\. CLI entry: %LOCALAPPDATA%\hermes\bin\. WSL2 installs under ~/.hermes.

The shared "After installation" block on the README still shows source ~/.bashrc. That is a bash command. A PowerShell-specific reload command was not on the Windows section that was opened. UNVERIFIED whether a new PowerShell window is required before hermes is on PATH.

Optional, after a CLI install, to build and launch Desktop:

hermes desktop

Conflict: providers page still says Windows must use WSL2

https://hermes-agent.nousresearch.com/docs/integrations/providers , section "WSL2 Networking (Windows Users)":

Since Hermes Agent requires a Unix environment, Windows users run it inside WSL2.

That sentence contradicts the README and the installation guide, which document a native Windows install. Both pages were live on 2026-11-14. For a Windows 11 desktop or PowerShell install, the install guide is the page that describes the supported method. The providers page's WSL2 section still matters if Hermes is running inside WSL2 and the model server (Ollama, LM Studio, llama-server) is on the Windows host: localhost inside WSL2 is the Linux VM, not Windows, unless Windows 11 22H2+ mirrored networking is turned on (networkingMode=mirrored in %USERPROFILE%\.wslconfig, then wsl --shutdown).

What the source installer adds by default

Installation guide: PM also installs browser and computer-use tools by default — a pinned Chromium (Chrome for Testing) and cua-driver on macOS, Windows, and glibc Linux. Skip flags: --skip-browser / -SkipBrowser and --skip-computer-use / -SkipComputerUse. Later hermes update does not add them back if they were skipped.

Antivirus friction on Windows (documented)

README troubleshooting: Windows Defender or other antivirus may quarantine uv.exe at %LOCALAPPDATA%\hermes\bin\uv.exe. The project calls this a false positive on Astral's uv package manager. Documented whitelist (Admin PowerShell):

Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"

The README also gives a longer gh attestation verify procedure against astral-sh/uv. That procedure is for checking the binary, not for installing Hermes.

3. Skills, memory, session search, cron, messaging, Bot Mode, desktop screen

Self-improving skills

Docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/skills

Skills are on-demand knowledge documents, compatible with the agentskills.io standard. They are not all loaded every turn. The agent can create, update, and delete its own skills with the skill_manage tool. The docs call this procedural memory: when it figures out a non-trivial workflow, it saves the approach for reuse.

The system prompt asks it to record a workflow when it worked out a multi-step path, hit dead ends and found a working path, or the user corrected it. A background review can also suggest or stage skill changes after a turn. A curator consolidation pass is a third writer. New agent-created skills go to ~/.hermes/skills/. The curator does not modify project skill directories.

Default write policy, quoted from that page:

By default the agent writes skills freely — including from the background self-improvement review that runs after a turn.

skills.write_approval: false is that default. Set it to true and writes are staged for /skills approve instead of landing immediately. The gate does not cover direct edits of skill files by the generic file tools or the terminal.

A locked skill (hermes curator lock, or the lock switch in Desktop) cannot be changed by skill_manage, write_file, patch, or terminal, including in YOLO mode. v0.23.0 notes say built-in skills went from 58 to 44 in that release. That count is from the v0.23.0 notes, not re-counted in the repo on 2026-11-14.

README marketing line: "Autonomous skill creation after complex tasks. Skills self-improve during use." The skills page is more precise: creation is prompted for non-trivial workflows, and improvement can come from the foreground agent, the background review, or the curator. It is on by default, with an opt-in approval gate.

Memory

Docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/memory

Two bounded files, injected into the system prompt at session start:

Stored in ~/.hermes/memories/ for the default profile. The agent writes them with the memory tool. Memory does not auto-compact: a write that would exceed the limit returns an error and the agent is supposed to make room. The prompt copy is a frozen snapshot for the session; edits hit disk immediately but the running session does not see them until the next session.

The page's own troubleshooting says the common failure is the model saying it remembered something without calling the memory tool. It specifically says small local models (roughly under 30B parameters) and models with weak tool-calling do this often. Memory is per profile: a CLI default profile and a Telegram bot on another profile do not share notes.

External memory plugins exist (the page names RetainDB and ByteRover as shipped plugins, and Honcho, Hindsight, Supermemory, Mem0, OpenViking, and Holographic as catalog installs). Honcho is the "dialectic user modeling" named in the README. It is optional, not the default store.

Nudges: memory.nudge_interval and skills.creation_nudge_interval exist. The README's "nudges itself to persist knowledge" matches this mechanism. Exact default interval numbers were not copied out of the configuration reference in this pass. UNVERIFIED as a number of turns.

Session search

Memory page:

All CLI and messaging sessions are stored in SQLite (~/.hermes/state.db) with FTS5 full-text search. Search queries return actual messages from the DB — no LLM summarization, no truncation.

The agent uses a session_search tool and can scroll inside a found session. The page contrasts this with memory: memory is ~1,300 tokens always in the prompt; session search is "unlimited (all sessions)," with the page's own timing claim "~20ms FTS5 query, ~1ms scroll," and "Free — no LLM calls."

Browse command:

hermes sessions list

Conflict with the README. The README says "FTS5 session search with LLM summarization for cross-session recall." The memory doc says the search returns messages with no LLM summarization. Both were fetched 2026-11-14. The detailed tool page is the one that describes the mechanism. The README sentence should not be treated as the tool's behavior without checking which part of the product still summarizes.

Session boundaries matter. On messaging platforms a chat is one continuous session across restarts. The memory page says if you never /new, the learning loop of forget → recall from memory → search past sessions almost never fires, and the chat gets expensive. On the CLI, each invocation is mostly a new session.

Cron / scheduled jobs

Docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron

Schedule in natural language or cron expressions. The agent tool is cronjob_manage (one tool with actions, not separate tools). People can also use /cron or the CLI.

Examples from that page:

/cron add "in 30m" "Remind me to check the build"
/cron add "every 2h" "Check server status"

hermes cron create "every 2h" "Check server status"

In chat, the documented natural-language example is: "Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram."

What the page says cron can do: one-shot or recurring tasks; stop a run already in flight; deliver results to the origin chat, local files, or configured platform targets; a no-agent mode that runs a script and delivers stdout with no LLM call; webhook-triggered jobs.

The gateway runs the scheduler. Messaging overview: "The gateway also runs the cron scheduler, ticking every 60 seconds." Cron page: agent jobs execute inside the gateway, and a tick never starts a gateway. With no gateway up, agent jobs are skipped and fire on a later tick after hermes gateway start. Their schedule is not advanced as a penalty. no_agent script jobs can still run from a bare tick.

So a schedule on a home PC does not run while the Hermes process is stopped. Homepage FAQ: "Tasks that need an active agent will not run while it is stopped; hosted agents are managed separately in Nous Portal." The desktop marketing line on https://hermes-agent.nousresearch.com/ai-models says the desktop agent works "while your machine is awake."

Dangerous commands during cron: approvals.cron_mode default is deny (security page). A cron job that hits a dangerous command is denied unless that setting is changed to approve.

Delivery targets must be known platforms with gateway credentials, except local / origin. Model resolution at fire time: per-job pin, else cron.model, else the main model from hermes model.

Messaging gateways — which apps

Overview: https://hermes-agent.nousresearch.com/docs/user-guide/messaging

Opening sentence, fetched 2026-11-14:

Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, Yuanbao, Microsoft Teams, LINE, ntfy, or your browser.

The comparison table on that same page also lists Google Chat, WhatsApp Cloud API, WeCom Callback, Photon (iMessage), Raft, IRC, Buzz, and SimpleX. Home Assistant is marked "(plugin)." Yuanbao is marked "(Labs plugin)."

README's short list is Telegram, Discord, Slack, WhatsApp, Signal, and CLI. Homepage features line is Telegram, Discord, Slack, WhatsApp, Signal, Email, CLI, "and a growing list."

Setup commands from the README and messaging page:

hermes gateway setup
hermes gateway start

The gateway is one background process for every configured platform. It also runs cron. Unknown DM senders get a pairing code, except email, where unknown senders are ignored unless email pairing is turned on.

Telegram has a Desktop/dashboard "Create with QR" path (https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram). Hermes Cloud with Team Gateway uses a shared bot instead of a bot you create; the card then says "Via Team Gateway."

WhatsApp (https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp): the built-in bridge is Baileys, emulating WhatsApp Web, not the official Business API. The page itself says this path has ban risk. A separate WhatsApp Business Cloud API guide is the official Meta path and needs a Meta Business account and a public webhook. For a dedicated bot number the page lists Google Voice (free, US only), a prepaid SIM it prices at "$5–15 one-time," or VoIP at "Free–$5/month," and warns some VoIP numbers are blocked.

Phone chat is not a Hermes app install on the phone. It is a bot in one of those apps, talking to a gateway that is running on a computer, a VPS, or Hermes Cloud.

Bot Mode and group chats

Docs: https://hermes-agent.nousresearch.com/docs/user-guide/bot-mode

Bot Mode ships built into the desktop app and is on by default — no install needed. It appears as a Bots tab next to Sessions in the left sidebar, with a Routines tile docked beside the conversation while the Bots tab is active.

A Bot is a Hermes profile: isolated config, memory, skills, credentials, and chat history under ~/.hermes/profiles/<name>/. CLI view of the same agent: hermes -p <name> chat. Bot routines show up in hermes cron list.

What Bot Mode adds, from that page's table: one permanent Bot Chat per bot (/new compacts instead of forking); a roster; bots can message each other and share group chats; each bot's routines are edited beside its chat.

Group chats: a room of 2–6 bots. Your message triggers up to three serial rounds. @-mentioned bots respond; if nobody is mentioned, who answers is a room setting: Everyone (the default), a lead, or an automatic router. Hard cap of 10 messages per send. On a gateway-owned room the cap pauses the room and offers Continue (up to 5 times) and Stop.

Gateway-owned group chats keep running when Desktop is closed. The dialog text quoted on that page: "Runs on 〈owner〉, including when this Desktop is closed. Only text is sent to bots on other computers." Bots on other machines join through their own gateways. v0.23.1 notes also say group chats can run on a gateway without Desktop and can seat bots from other computers.

This is a different feature from a Telegram/Discord group. Messaging platforms have their own group-chat silence and admin rules. Bot Mode rooms are inside Hermes Desktop / the gateway.

Desktop screen per bot — yes, and it needs Linux

Docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/bot-screen

On a headless Linux gateway host (a server, a cloud VM, Hermes Cloud) each bot gets its own desktop: an Xfce screen the bot's computer_use and headed browser act on, streamed live into Hermes Desktop.

Requirements copied from that page:

• The gateway host runs Linux. "macOS and Windows hosts already have a real display; the pane is not offered there."
• WSL2 counts as a supported Linux host, and the pane is offered there.
• TigerVNC Xvnc and Xfce core components must be installed. Nothing installs them silently. The Desktop pane shows "Install on host," which runs the package manager and asks for that host's sudo password. The password is not stored.
• The screen is off by default. Someone clicks Start screen, or runs hermes computer-use screen start, or sets bot_desktop.auto_start: true.
• Each profile has its own screen, browser profile, and cookies. The page says screens are work surfaces, not security boundaries: bots share the host's user account, files, and network.

Where it is allowed to run (bot_desktop.placement):

Memory numbers published on that page, "measured in the official image": gateway idle ~300 MB; Xvnc + Xfce add ~220 MB; a headed Chromium during takeover adds 0.5–1 GB (one page ~550 MB). Plan on ~1.1–1.5 GB per open screen with a browser. Packages ~930 MB disk on Debian 13. Free-memory check default bot_desktop.min_free_memory_mb: 1536. Idle stop default: 30 minutes. CPU figures on that page: idle desktop ≈ 0.01 core, live streaming ≈ 0.03 core. Practical guidance there: "4 GB runs the desktop, 8 GB is where a takeover with a browser is comfortable" — the fetched sentence was cut after "is". The 4 GB / 8 GB clause is what was visible.

A Windows 11 or macOS desktop user does not get this per-bot virtual screen on that same machine. They can watch one if they connect Desktop to a Linux gateway that has it. On Mac and Windows the agent can still drive the real machine through the local terminal and the computer-use driver the installer adds by default. That is the host desktop, not a per-bot Xfce screen.

4. Default safety: smart approvals, host shell, sandboxes

Security: https://hermes-agent.nousresearch.com/docs/user-guide/security

Configuration (terminal backends): https://hermes-agent.nousresearch.com/docs/user-guide/configuration

Tools page: https://hermes-agent.nousresearch.com/docs/user-guide/features/tools

The shell runs on the host unless you change it

Configuration page, default:

terminal:
  backend: local   # local | docker | ssh | modal | daytona | vercel_sandbox |

The default. Commands run directly on your machine with no isolation. No special setup required.

Local subprocesses keep the real OS-user HOME, so git, ssh, gh, npm, Claude Code, and Codex can see the credentials already on that account. Hermes state is still under HERMES_HOME.

README's list of built-in backends: "local, Docker, SSH, Modal, Daytona, and Vercel Sandbox," plus plugin backends such as Singularity/Apptainer. The tools page also names plugin backends singularity and sprites (Fly.io).

Homepage feature card says "Five backends — local, Docker, SSH, Singularity, Modal." That marketing line omits Daytona and Vercel Sandbox and includes Singularity, which the docs call a plugin. The configuration page is the list of terminal.backend values.

What "smart" approvals actually do

They are not a sandbox. They are a second look at commands that already matched a dangerous-pattern list.

Security page, first statement of the layer:

Before executing any command, Hermes checks it against a curated list of dangerous patterns. If a match is found, the user must explicitly approve it.

Then the mode table. Default approvals.mode is smart.

So "smart" does not approve every command, and it does not ask about every command. Commands that do not match the dangerous-pattern list are not described as prompting. Commands that do match are classified by another model call: allow this once, deny, or ask the human.

Other defaults in the same config block:

• timeout: 300 seconds
• cron_mode: deny
• single_query_mode: deny
• unattended_mode: deny (webhooks and API sessions)

/yolo and approvals.mode: off skip the prompts for that session or profile. There is also a hard blocklist under YOLO (fork bomb and similar) that the page says cannot be overridden, plus optional user approvals.deny globs.

Container bypass, same page:

When running in docker, modal, daytona, or vercel_sandbox backends (or a container plugin backend such as singularity or sprites), dangerous command checks are skipped because the container itself is the security boundary.

SSH is not in that skip list. SSH is a network boundary (commands run on the remote machine). Docker is described as full isolation with capabilities dropped. Modal and Daytona are described as full cloud isolation. Local is "None."

execute_code caveat on the security page: a script can call subprocess, os, or shutil without passing the shell pattern list. Messaging and API sessions ask once for the whole script. Local CLI, TUI, Desktop, and ACP sessions do not, when the viewer typed the turn and a viewer is attached: Python-level file and process operations inside the script run without a prompt, and only the script's terminal() calls ask.

File writes have a separate denylist (no approval prompt, the write is refused). That includes Windows NT device-namespace paths. It is not a full filesystem sandbox. HERMES_WRITE_SAFE_ROOT is an optional extra sandbox; the official Docker image sets it to /opt/data.

DM pairing is a separate layer for who may talk to a messaging bot. It does not sandbox the shell.

Safe-by-default, stated plainly: approval mode defaults to smart, and unattended/cron dangerous commands default to deny. The terminal defaults to the host with no isolation. Skill writes default to free. Container backends are opt-in, and once selected they skip dangerous-command checks. A non-technical person who installs Desktop and picks a model is not inside a sandbox.

5. Models

Provider page: https://hermes-agent.nousresearch.com/docs/integrations/providers

You need at least one provider. hermes model is the setup wizard. /model inside a chat only switches among providers already set up.

The page's "Choosing the Right Setup" table lists "Just want it to work" as "OpenRouter (default) or Nous Portal." That is the table's label. A fresh install still has to log in or paste a key. hermes setup --portal is the documented one-command path for Nous.

OpenRouter

Table row:

OPENROUTER_API_KEY in ~/.hermes/.env, or hermes auth add openrouter --type oauth (browser login via OpenRouter's PKCE flow; stores a key in the credential pool).

The same page has OpenRouter provider routing (provider_routing in config.yaml) and an experimental Pareto Code router at model id openrouter/pareto-code. Auxiliary tasks can be pointed at a cheaper OpenRouter model (the page's example is Gemini Flash).

No OpenRouter dollar prices were copied from an OpenRouter pricing page in this pass. UNVERIFIED as a price list.

Gemini

Table row: GOOGLE_API_KEY or GEMINI_API_KEY in ~/.hermes/.env, provider id gemini.

There is no documented sign-in with a consumer Gemini subscription. Quoted from the subscription table and the paragraph under it:

Google — Gemini consumer plan (Google AI Pro / Ultra) | No documented path — the gemini provider is API-key only (GOOGLE_API_KEY / GEMINI_API_KEY); Vertex AI uses GCP billing.

There is currently no way to sign in to Hermes with a consumer Gemini subscription — the gemini provider takes an API key, and Google Vertex AI bills to your GCP project. A billing-enabled Google Cloud project is recommended for agent use; free-tier quotas are too small for long-running agent sessions.

The page's surprise column says free-tier keys can be exhausted after a handful of agent turns, because Hermes may make several model calls per user turn. Vertex AI is a separate section (OAuth2 / service account, not a static API key).

Local llama.cpp and Ollama

Both are custom OpenAI-compatible endpoints, not a separate "local" product mode. The page's general rule:

Hermes Agent works with any OpenAI-compatible API endpoint. If a server implements /v1/chat/completions, you can point Hermes at it.

Three setup paths: hermes model → "Custom endpoint (self-hosted / VLLM / etc.)"; or config.yaml with provider: custom and model.base_url; or, for the OpenAI provider only, OPENAI_BASE_URL overrides the OpenAI endpoint. For every other provider and for custom endpoints, the page says use hermes model or model.base_url in config.yaml. Named custom providers can be switched with /model custom:local:qwen-2.5.

Ollama (local). Not the same as the first-class "Ollama Cloud" provider. Cloud uses OLLAMA_API_KEY. Local is custom endpoint, no key:

ollama pull qwen2.5-coder:32b
ollama serve

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter URL: http://localhost:11434/v1
# Skip API key
# Enter model name (e.g. qwen2.5-coder:32b)

Equivalent config shape on that page:

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 64000

The page says Ollama's own default context is often too small (table: under 24 GB VRAM → 4,096 tokens; 24–48 GB → 32,768; 48+ GB → 256,000) and:

Hermes Agent requires at least 64,000 tokens of context for agent use with tools. Smaller windows are rejected at startup.

Context length cannot be set through the OpenAI-compatible API. It has to be set on the Ollama server or in a Modelfile. Tool calling is described as on by default in Ollama if the model supports it.

llama.cpp. Section title: "llama.cpp / llama-server — CPU & Metal Inference." Documented start (build, then server):

cmake -B build && cmake --build build --config Release
./build/bin/llama-server \
  --jinja -fa \
  -c 64000 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

Then hermes model → custom endpoint → http://localhost:8080/v1, skip the API key. --jinja is required or tool calls come back as plain text Hermes will not execute. The page says to set -c to at least 64,000. Native tool-calling families it names: Llama 3.x, Qwen 2.5 (including Coder), Hermes 2/3, Mistral, DeepSeek, Functionary.

LM Studio is a separate, easier local path on the same page (hermes model → "LM Studio", default URL http://localhost:1234/v1). It is not llama.cpp, but it is the GUI the docs point at for people who do not want to compile.

Custom OpenAI-compatible base URLs

Supported. model.base_url in ~/.hermes/config.yaml, or the custom-endpoint wizard. The page's example is http://localhost:8000/v1. Empty API key is allowed for local servers. Switching away from a custom endpoint to a built-in provider clears the stale base URL. This is the route for Ollama, llama-server, vLLM, SGLang, and any other /v1/chat/completions server.

Nous Portal prices (published)

Portal docs: https://hermes-agent.nousresearch.com/docs/integrations/nous-portal

Guide: https://hermes-agent.nousresearch.com/docs/guides/run-hermes-with-nous-portal

Plan tables, same numbers on the homepage and on https://hermes-agent.nousresearch.com/ai-models , fetched 2026-11-14:

Footer under that table: "Cancel anytime · Paid plans are billed monthly · Included usage has daily, weekly and monthly limits. Past them, switch to a free model, wait for the reset, or keep going on pay-as-you-go credits."

Prose on the same page: hosted tools (web search, image generation, text-to-speech, cloud browser) run through Nous on paid plans and count as usage. Homepage header above the table: "All paid tiers include usage in Hermes Agent, access to 200+ cutting-edge models, built-in tool use and one Cloud agent."

The markdown conversion left the pay-as-you-go top-up checkmarks blank. Which paid tiers show a checkmark in the rendered table is UNVERIFIED from the text extraction. The price row itself was plain text.

Configuration page, separate claim: "Portal subscribers also get 10% off token-billed providers." That sentence is on https://hermes-agent.nousresearch.com/docs/user-guide/configuration . It was not repeated on the plan table.

Model-count wording disagrees by page: Portal integration doc says "300+ frontier models"; homepage plan blurb says "200+"; the AI-models page says "Hundreds of models" and shows a catalog with per-million-token prices. Those catalog prices are a live list. This note does not copy them, because they are per-model rates on a page that can change, and the subscription table above is the published plan price. One catalog line was visible in the fetch (illustrative only, not a promise it is still that price): "Anthropic: Claude Haiku 4.5 in $1.00 / out $5.00 per 1M." Treat the whole catalog as "the page listed prices on 2026-11-14," not as a rate card to quote in a guide without opening it again.

Portal integration page also says one OAuth login covers the model catalog plus the Tool Gateway. Tool Gateway backends named there: web search (Nous-managed), image generation (FAL), text-to-speech (OpenAI TTS), cloud browser (Browser Use), cloud terminal sandbox (Modal, "optional add-on"). Login from a fresh install:

hermes setup --portal

Manage plans at https://portal.nousresearch.com/manage-subscription or hermes portal open.

Anthropic path: Claude Max, extra usage, Pro

Native provider section: https://hermes-agent.nousresearch.com/docs/integrations/providers

Quoted from "Anthropic (Native)":

When you authenticate via hermes model → Anthropic OAuth (or via hermes auth add anthropic --type oauth), Hermes routes as Claude Code against your Anthropic account. It only works if you're on a Claude Max plan and have purchased extra usage credits. The base Max plan allowance (the usage included in Claude Code by default) is not consumed by Hermes — only the extra/overage credits you've added on top are. Claude Pro subscribers cannot use this path.

If you don't have Max + extra credits, use an ANTHROPIC_API_KEY instead — requests are billed pay-per-token against that key's organization (standard API pricing, independent of any Claude subscription).

Subscription table, same page:

• Claude Max + OAuth: yes, requires Max and purchased extra usage credits. Consumes the extra/overage credits. Does not consume the base Max plan allowance. Surprise text: "All Hermes usage bills as extra usage even while your included Max allowance sits untouched."
• Claude Pro: "No — Pro subscribers cannot use the OAuth path." "Pro looks like it should work; it doesn't. Use an ANTHROPIC_API_KEY instead (pay-per-token, independent of any Claude subscription)."

API-key example on that page:

export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

The *** is how the fetched doc redacted the key, not a real key.

Credential-pools page repeats: hermes auth add anthropic --type oauth "requires Claude Max plan + extra usage credits." https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools

Separate experimental plugin, not the native path. Marketplace page https://hermes-agent.nousresearch.com/marketplace/claude-subscription-directsdk describes claude-subscription-directsdk as an experimental provider that runs turns through the Claude Code CLI / Agent SDK and says it can use a Claude Pro/Max subscription with no separate API key. Its own disclosure: "every turn is billed against your Claude subscription's Agent SDK allowance." That plugin is not the hermes model → Anthropic OAuth path quoted above. The native path is the one that refuses Pro and does not consume base Max allowance.

Claude models are also reachable through Nous Portal and through OpenRouter, billed by those accounts, not by a Claude subscription.

6. What a non-technical person would find hard

These are frictions written on the official pages, not a guess about a specific person.

1. Something else has to be paid for and logged into before the first reply. The agent is MIT-licensed and free. A provider is mandatory. The fastest documented path is still a Nous Portal subscription (hermes setup --portal) or an API key. Free Portal tier is "Free models only."

2. Claude subscription surprises. Pro cannot use the native OAuth path. Max does not spend the included Claude Code allowance. Hermes draws purchased extra-usage credits. Someone who already pays for Claude can still get a separate bill. The experimental Agent SDK plugin is a different, opt-in route and is labeled experimental.

3. Gemini consumer plans do not sign in. A Google AI Pro/Ultra subscription is not a documented Hermes login. The Gemini path is an API key, and the docs warn that free-tier keys die after a handful of agent turns.

4. Two install stories on Windows and a stale Unix warning. Supported native path is PowerShell iex (irm ...), or an MSIX that needs Windows 11 22H2+, or the Store, or an .exe the homepage advertises for Windows 10/11. The providers page still says Hermes requires Unix and Windows users run it inside WSL2. Antivirus may quarantine uv.exe. The after-install snippet in the README is source ~/.bashrc, which is not PowerShell.

5. Mac desktop is Apple Silicon only. Intel Macs are told to use the CLI and hermes desktop, which builds the app. Homepage says macOS 12+; v0.23.0 notes say macOS 13+. A person with an Intel Mac or an older macOS can follow the homepage and hit a platform the install guide does not support.

6. The default is a shell on the PC, with an AI deciding which dangerous commands to allow. Smart mode is the default, and it auto-approves some commands that matched the dangerous list, using a second model call. It is easy to read "approvals" as "it always asks." It does not. Containers are safer and are not the default. Turning Docker/Modal/Daytona on skips the dangerous-command prompts entirely.

7. It rewrites its own skills unless you change a setting. Skill writes default to free, including a background review after a turn. Memory only sticks if the model actually calls the memory tool. The docs say weaker models often claim they saved a fact and did not.

8. Phone chat and schedules are a second project. You configure a bot (Telegram QR is the easiest documented path; WhatsApp's easy path is an unofficial bridge the docs say can get the number banned). The gateway process has to stay running. A home install stops when the computer sleeps or the app quits. Hermes Cloud is the documented always-on option and is a paid Portal feature (one hosted agent on paid plans, sized in the table above).

9. Per-bot desktops are a Linux server feature. The screen pane is not offered on macOS or Windows hosts. It needs TigerVNC and Xfce, a sudo install, and about 1.1–1.5 GB RAM once a browser is open. Modal and Daytona cannot host that screen.

10. Local models are a systems task. Ollama and llama.cpp are custom base URLs. llama.cpp's documented path compiles with cmake. Hermes refuses context windows under 64,000 tokens. Ollama's default context is often 4,096. Tool calling needs the right server flag (--jinja on llama-server).

11. Words overlap. A "bot" can mean a Desktop profile, a Telegram bot, or a subagent. A "group chat" can mean a Bot Mode room or a WhatsApp group. A "sandbox" can mean the terminal backend, a per-bot Xfce screen, or a write-root. The docs use all of these.

12. The surface area is large. Messaging comparison table lists more than twenty platforms, many of them regional or plugin-based. Setup for each one is tokens, QR codes, or webhooks, then pairing so strangers cannot DM the bot.

7. Facts for the scorecard

Checked 2026-11-14 against the pages cited above.

Everyday capability ceiling. High, if a strong model is connected and the computer (or a cloud agent) stays on. One install can chat in a desktop window, run a shell and edit files, browse the web, keep bounded memory, write its own skills, search past sessions, run scheduled jobs, and talk through a long list of chat apps. It can spawn subagents. On a Linux host it can give each bot a virtual Xfce screen. On a normal Windows or Mac install the shell is that PC, and there is no per-bot virtual screen. It is not a phone app. Small local models are a lower ceiling: the docs require 64k context and say models under roughly 30B often fail to call the memory tool. Schedules do not fire while the gateway process is stopped.

Windows / Mac install friction. Desktop is the lower-friction path when the machine matches the package: Apple Silicon Mac, DMG, copy Hermes.app to Applications; Windows 11 22H2 or later, .appinstaller / MSIX, or the Microsoft Store. Friction goes up for Intel Macs (no desktop bundle), Windows 10 (CLI is Tier 1, MSIX is not), the PowerShell one-liner (remote script, Python/Node bootstrap, possible Defender flag on uv.exe), and anyone who hits the providers page's outdated "must use WSL2" sentence. Homepage OS labels (macOS 12+, Windows 10/11) are looser than the install and platform pages.

Safe-by-default. Not sandboxed by default. Default terminal backend is local: commands run on the host with no isolation. Default approval mode is smart: an auxiliary model auto-approves some dangerous-pattern commands, auto-denies others, and asks when unsure. Cron and other unattended dangerous commands default to deny. Skill self-writes default to on. Docker, SSH, Modal, Daytona, and Vercel Sandbox are available and off until configured. Docker, Modal, Daytona, and Vercel Sandbox then skip dangerous-command checks. SSH does not get that skip.

Model-route flexibility. High. Documented first-class routes include Nous Portal, OpenRouter (API key or OAuth), Anthropic (Max extra-usage OAuth, or API key), Google Gemini (API key only), and many other API-key providers. Custom OpenAI-compatible base URLs are a supported provider: custom / model.base_url path, which is how local Ollama (http://localhost:11434/v1) and llama-server (http://localhost:8080/v1) are wired. OPENAI_BASE_URL only overrides the OpenAI provider. Claude Pro cannot use native Anthropic OAuth. A consumer Gemini plan cannot be signed into. Portal plan prices published on the site: Free $0 pay-as-you-go, Plus $20/month, Super $100/month, Ultra $200/month.

One install grows from desktop to phone chat and schedules. Yes, as a product design, with extra setup and a process that stays running. Desktop, CLI, and the messaging gateway share HERMES_HOME and, on the same profile, the same memory and skills. Phone access is a gateway platform (Telegram is the path with a QR creator in Desktop), not a mobile install. Cron is built in and can deliver to that chat, but agent cron runs inside the gateway. The home machine must be awake, or the agent must be moved to a VPS or to Hermes Cloud (one hosted agent is included on paid Portal plans, at the RAM/disk sizes in the table). Closing the laptop stops a local agent. Bot Mode group chats that the gateway owns keep running when Desktop is closed, as long as that gateway stays up.

Sources

All fetched 2026-11-14.

1. https://api.github.com/repos/NousResearch/hermes-agent — stars 263308, MIT, created 2025-07-22, description, forks, open_issues_count.
2. https://api.github.com/repos/NousResearch/hermes-agent/releases?per_page=5 — v0.23.1 published 2026-11-10T01:42:15Z (not pre-release); canary v0.23.1+canary.20261114T064334Z published 2026-11-14T07:46:34Z (pre-release); v0.23.0 published 2026-11-05T21:32:33Z.
3. https://github.com/NousResearch/hermes-agent/releases — release-note dates (November 9, 2026 for v0.23.1; November 14, 2026 for that day's canary) and the v0.23.0 macOS 13+ / 64-bit Windows sentence.
4. https://raw.githubusercontent.com/NousResearch/hermes-agent/main/README.md — product description, install commands, backends, learning loop, license, Windows native path, uv.exe troubleshooting.
5. https://hermes-agent.nousresearch.com/ — MIT FAQ, macOS 12+, Windows 10/11, Store and .exe, five-backend marketing line, Portal plan table.
6. https://hermes-agent.nousresearch.com/docs/getting-started/installation — desktop DMG/MSIX steps, install commands, stable channel, Python 3.14, Apple Silicon note, data directories.
7. https://hermes-agent.nousresearch.com/docs/getting-started/platform-support — Tier 1 matrix, MSIX requires Windows 11 22H2+, Intel Mac desktop bundles unsupported.
8. https://hermes-agent.nousresearch.com/docs/user-guide/desktop — Apple Silicon / Windows / Linux, hermes desktop builds from source, shared HERMES_HOME.
9. https://hermes-agent.nousresearch.com/docs/user-guide/features/skills — skill_manage, default free writes, approval gate, lock.
10. https://hermes-agent.nousresearch.com/docs/user-guide/features/memory — MEMORY.md / USER.md limits, session_search FTS5 with no LLM summarization, weak-model failure mode.
11. https://hermes-agent.nousresearch.com/docs/user-guide/features/cron — natural-language schedules, gateway must be running, delivery.
12. https://hermes-agent.nousresearch.com/docs/user-guide/messaging — platform list and comparison table, gateway process, 60-second cron tick.
13. https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram — Create with QR; Team Gateway shared bot.
14. https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp — Baileys vs Cloud API, ban risk, number costs.
15. https://hermes-agent.nousresearch.com/docs/user-guide/bot-mode — Bot Mode on by default, group chats, runs when Desktop is closed.
16. https://hermes-agent.nousresearch.com/docs/user-guide/features/bot-screen — per-bot Xfce screen, Linux only, not offered on macOS/Windows, WSL2 counts, Modal/Daytona/Vercel refused, memory figures.
17. https://hermes-agent.nousresearch.com/docs/user-guide/security — smart/manual/off, cron deny, container bypass, execute_code local exemption.
18. https://hermes-agent.nousresearch.com/docs/user-guide/configuration — terminal.backend: local, backend list, 10% Portal discount sentence.
19. https://hermes-agent.nousresearch.com/docs/user-guide/features/tools — backend table including docker, ssh, modal, daytona, vercel_sandbox.
20. https://hermes-agent.nousresearch.com/docs/integrations/providers — OpenRouter, Gemini, Ollama, llama.cpp, custom base_url, Anthropic Max/Pro quotes, WSL2 sentence.
21. https://hermes-agent.nousresearch.com/docs/integrations/nous-portal — 300+ models wording, Tool Gateway including Modal sandbox.
22. https://hermes-agent.nousresearch.com/docs/guides/run-hermes-with-nous-portal — hermes setup --portal, subscription manager URL.
23. https://hermes-agent.nousresearch.com/ai-models — same $0 / $20 / $100 / $200 plan table, hosted-tools prose, desktop "while your machine is awake."
24. https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools — Anthropic OAuth requires Max plus extra usage credits.
25. https://hermes-agent.nousresearch.com/marketplace/claude-subscription-directsdk — experimental Pro/Max path through Claude Code CLI; not the native OAuth path.