Reference

Look-up facts for Hermes Agent: releases, platform support, install layouts, defaults, config keys, limits, ports, providers, and known advisories. For why things work the way they do, see Explanation; for step-by-step tasks, see How-to Guides.

Fast-moving project

Hermes Agent ships a tagged release roughly every 3-7 days (each rolling up hundreds of PRs). Every number on this page is dated; re-check the releases page and the docs before relying on a default.

Release History

Releases carry both a semantic version and a calendar tag (vYYYY.M.D). Docker images use the calendar tag (for example nousresearch/hermes-agent:v2026.9.24).

Version	Tag	Date	Notes
0.21.5	v2026.9.24	2026-09-24	Latest. ~460 PRs rollup: desktop plugin SDK, Simple/Advanced desktop mode, Connectors page (MCP), French/German/Spanish UI catalogs, new model entries. Curated notes deferred to 0.22.0
0.21.4	v2026.9.21	2026-09-21	Patch rollup
0.21.3	v2026.9.14	2026-09-14	Remote gateway sign-in fixes
0.21.2	v2026.9.11	2026-09-11	Database reliability patch
0.21.1	v2026.9.7	2026-09-07	Main-branch rollup
0.21.0 "Pantheon"	v2026.8.31	2026-08-31	Bot Mode (named agents with group chats), hermes peer agent-to-agent messaging, cron jobs with persistent memory, live subagent control, MCP command center, 6 new inference providers, write approval for protected instruction files (AGENTS.md, skills, memory)
0.20.6	v2026.8.27	2026-08-27	Infrastructure patch
0.20.0 "Herald"	v2026.8.3	2026-08-03	Streaming voice with barge-in and wake words, A2A v1.0, signed outbound webhooks, grounded research with citations, desktop artifacts + plugin SDK. Install channels narrowed to shell installer, Docker, and Nix; brew and PyPI wheels retired. Node 26 required
0.19.0	—	2026-07-20	Last version published to PyPI
0.15.0 "Velocity"	v2026.5.28	2026-05-28	run_agent.py split into agent/ modules (-76% lines); multi-agent kanban platform
0.14.0 "Foundation"	v2026.5.16	2026-05-16	xAI Grok OAuth, OpenAI-compatible subscription proxy, lighter installs
0.13.0 "Tenacity"	v2026.5.7	2026-05-07	Durable multi-agent kanban board, /goal standing goals
0.12.0	v2026.4.30	2026-04-30	—
0.11.0	v2026.4.23	2026-04-23	—
0.10.0	v2026.4.16	2026-04-16	—
0.9.0	v2026.4.13	2026-04-13	Version this vault first documented
0.8.0	v2026.4.8	2026-04-08	—

Sources: GitHub releases, v0.21.0 notes, v0.20.0 notes, PyPI history.

PyPI version lag

PyPI still shows hermes-agent 0.19.0 (2026-07-20). That is not the latest release: PyPI publishing stopped when v0.20.0 retired pip installs. Use the GitHub release tags as the source of truth.

Platform Support Matrix

Tier	OS / arch	Install methods	Notes
Tier 1	macOS (Apple Silicon)	Hermes Desktop DMG, install.sh	Intel macOS is not a Tier 1 platform
Tier 1	Windows 10/11 (x86_64, aarch64)	install.ps1, MSIX desktop	MSIX needs Windows 11 22H2+
Tier 1	Linux / WSL2 (x86_64, aarch64)	install.sh	Tested on latest Ubuntu and WSL2
Tier 1	Docker (amd64, arm64)	docker pull nousresearch/hermes-agent	hermes update not supported; pull a new image
Tier 2	Nix (macOS, Linux, NixOS)	Nix flake and modules	Best effort only
Tier 2	Android / Termux (aarch64)	Signed APT repo, pkg install hermes-agent	Android may kill background processes
Unsupported	—	PyPI (pip/uv tool install hermes-agent), Homebrew, AUR, non-aarch64 Termux	PRs to fix these are not accepted

Source: Platform Support.

Runtime Requirements

Item	Value	Source
Python (first-party installs)	3.14, provided by the PM tool manager	Installation
requires-python in pyproject.toml	>=3.11,<3.15; the range exists only so old installs can run the updater	pyproject.toml
Node.js	Provided by PM; v0.20.0 notes state Node 26 required	v0.20.0 notes
Other managed tools	npm, ripgrep, FFmpeg, agent-browser + pinned Chromium (skippable with --skip-browser)	Installation
POSIX installer prerequisites	Git, curl, tar, SHA-256 utilities	Installation
Dependency policy	Core dependencies exact-pinned (==X.Y.Z) by policy since 2026-05-12, after a PyPI supply-chain worm incident; a few (for example fastapi, urllib3) keep bounded ranges	pyproject.toml
GPU	Not required; inference goes to a provider API or a local server	README

Install Layout

Method	Code	CLI entry point	Default user data
POSIX source script	~/.hermes/hermes-agent/	~/.local/bin/hermes wrapper	~/.hermes/
Windows source script	%LOCALAPPDATA%\hermes\hermes-agent\	%LOCALAPPDATA%\hermes\bin\	%LOCALAPPDATA%\hermes\
Desktop bundle	Inside the app package	Packaged launchers	Platform default data dir
Docker	/opt/hermes/ (read-only)	Image entrypoint + hermes shim	Mounted /opt/data/
Termux APT	$PREFIX/lib/hermes-agent/	Symlinks in $PREFIX/bin/	~/.hermes/

HERMES_HOME selects the user-data root. Named profiles live under ~/.hermes/profiles/<name>/.

Files Under ~/.hermes/

Path	Contents
config.yaml	All non-secret settings
.env	API keys and other UPPER_SNAKE environment settings
auth.json	OAuth credentials (Nous Portal, Codex, and others)
state.db	SQLite session store (WAL mode) with FTS5 indexes
memories/MEMORY.md, memories/USER.md	Built-in persistent memory
SOUL.md	Global persona for this Hermes instance
skills/	Bundled, hub-installed, and agent-created skills; skills/.archive/ holds curator-archived skills
pending/skills/	Skill writes staged by skills.write_approval
plugins/	User plugins
hooks/<name>/	Gateway event hooks (HOOK.yaml + handler.py)
logs/	agent.log, errors.log, gateway.log, gui.log, desktop.log
checkpoints/	Shadow store for /rollback
cache/scratch/	Per-profile TMPDIR for Hermes processes

Terminal Backends

Seven backends decide where the agent's shell, file, and execute_code calls run (terminal.backend).

Backend	Where commands run	Isolation	Dangerous-command check	Key settings
local (default)	Host machine	None	Yes	cwd, timeout
docker	One long-lived container shared across sessions (default)	Namespaces, cap-drop	Skipped	docker_image, docker_volumes, docker_forward_env, container_persistent
ssh	Remote host over SSH	Network boundary	Yes	TERMINAL_SSH_HOST, TERMINAL_SSH_USER, TERMINAL_SSH_KEY
modal	Modal cloud sandbox	Cloud VM	Skipped	MODAL_TOKEN_ID/MODAL_TOKEN_SECRET, modal_image
daytona	Daytona workspace	Cloud container	Skipped	DAYTONA_API_KEY, max 10 GiB disk
vercel_sandbox	Vercel Sandbox microVM	Cloud microVM	Skipped	VERCEL_TOKEN + VERCEL_PROJECT_ID + VERCEL_TEAM_ID; runtime node24 (default), node22, python3.13
singularity	Singularity/Apptainer container	Namespaces (--containall)	Skipped	singularity_image

Defaults: per-command timeout: 180 s; container image nikolaik/python-nodejs:python3.11-nodejs20 for Docker, Modal, Daytona, and Singularity; container_cpu: 1, container_memory: 5120 MB, container_disk: 51200 MB; Docker idle lifetime_seconds: 300.

Source: Configuration: Terminal Backends, Security: backend comparison.

Docker Sandbox Security Flags

The base docker run flags from the security docs:

Flag	Purpose
--cap-drop ALL then --cap-add DAC_OVERRIDE, CHOWN, FOWNER	Drop all capabilities except those package managers need
--security-opt no-new-privileges	Block privilege escalation
--pids-limit 256	Fork-bomb protection
--tmpfs /tmp:rw,nosuid,size=512m	Size-limited /tmp
--tmpfs /var/tmp:rw,noexec,nosuid,size=256m	No-exec /var/tmp
/run tmpfs	Mounted per image, noexec by default
SETUID/SETGID	Added only when an s6 entrypoint must drop root privileges
docker_network: false	Runs with --network=none (air-gapped)

Memory Architecture

Layer	Storage	Scope	Retrieval	Default
Session context	In-memory message list	Current conversation	Always in context; compressed near the limit	On
Persistent memory	MEMORY.md (2,200 chars) + USER.md (1,375 chars)	Per profile, across sessions	Frozen snapshot in the system prompt at session start	On
Session history	state.db (SQLite + FTS5)	All past sessions in the profile	session_search tool; no LLM calls, ~20 ms query	On
External memory provider	Honcho, Mem0, OpenViking, and others	Provider-defined	Prefetch + provider tools	Off (one active at a time)
Skills	SKILL.md directories	Persistent procedures	Progressive disclosure (skills_list then skill_view)	On

Memory Config Keys

Key	Default	Meaning
memory.memory_enabled	true	Enable MEMORY.md
memory.user_profile_enabled	true	Enable USER.md
memory.memory_char_limit	2200	About 800 tokens
memory.user_char_limit	1375	About 500 tokens
memory.nudge_interval	10	Remind the agent to consider saving memory every N user turns (0 = off)
memory.write_approval	false	true stages writes for /memory pending review
memory.provider	unset	External provider name
skills.creation_nudge_interval	15	Remind the agent to consider saving a skill every N tool-calling iterations (0 = off)
skills.write_approval	false	true stages every skill_manage write under ~/.hermes/pending/skills/
auxiliary.background_review.enabled	true	Post-turn self-improvement review fork
auxiliary.background_review.model	auto	auto = main chat model; a different model runs on a digest (~3-5x cheaper per the docs)
display.memory_notifications	on	off, on, or verbose gateway notices

Sources: Persistent Memory, cli-config.yaml.example.

External Memory Providers

Provider	Storage	Cost	Unique feature
Honcho	Cloud or self-hosted	Paid (cloud) / free (self-hosted)	Dialectic user modeling
OpenViking	Self-hosted	Free (AGPL-3.0)	Filesystem hierarchy, tiered loading
Mem0	Cloud, self-hosted, or OSS	Free / paid	Server-side LLM extraction
Hindsight (plugin catalog)	Cloud or local	Free / paid	Knowledge graph + reflect synthesis
Holographic	Local	Free	HRR algebra + trust scoring
RetainDB	Cloud	$20/mo (per docs)	Delta compression
ByteRover	Local or cloud	Free / paid	Pre-compression extraction
Supermemory	Cloud or self-hosted	Free / paid	Context fencing, session graph ingest
Memori	Cloud	Free / paid	Tool-aware memory, structured recall

Seven providers are bundled (Honcho, OpenViking, Mem0, Holographic, RetainDB, ByteRover, Supermemory). Hindsight comes from the plugin catalog (hermes plugins install hindsight), and Memori needs the externally supplied hermes-memori integration. Sources: Memory Providers, CLI reference: hermes memory.

Honcho Settings (Selected)

Key	Default	Meaning
recallMode	hybrid	hybrid (auto-inject + tools), context (inject only), tools (tools only)
contextTokens	null	Token budget for injected context per turn
dialecticCadence	2	Minimum turns between peer.chat() dialectic calls
dialecticDepth	1	Dialectic passes per call (1-3)
writeFrequency	async	async, turn, session, or integer N
sessionStrategy	per-directory	per-directory, per-repo, per-session, global

The hermes honcho subcommand only exists while memory.provider: honcho is active. Source: Honcho Memory.

Skills Reference

Skill Locations and Precedence

Tier	Path	Notes
Project (highest)	<repo>/.hermes/skills/, <repo>/.agents/skills/	Loaded only after hermes skills trust; curator never edits them
Local	~/.hermes/skills/	Bundled, hub-installed, and agent-created skills
External	skills.external_dirs	Read-only for creation; existing skills are patched in place

Skill Document Format

Skills are directories with a SKILL.md (YAML frontmatter + standard sections) and optional references/, templates/, scripts/, assets/:

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]          # optional OS restriction
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]   # optional conditional activation
    requires_toolsets: [terminal]  # optional conditional activation
    config:                        # optional config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

skill_manage Actions

Action	Use for
create	New skill (full SKILL.md)
patch	Targeted old_string -> new_string edit (preferred)
patch with content	Full rewrite (edit is the legacy alias)
delete	Remove a skill
write_file / remove_file	Supporting files under the skill directory

Advisory linter rules: incident-log-shape, references-sprawl (more than 60 reference files), oversized-body (SKILL.md over ~24k chars). They warn but never block.

Skills Hub Sources

Source	Example identifier
official	official/security/1password
skills-sh	skills-sh/vercel-labs/agent-skills/vercel-react-best-practices
well-known	well-known:https://mintlify.com/docs/.well-known/skills/mintlify
url	https://example.com/SKILL.md
github	openai/skills/k8s
clawhub, lobehub, browse-sh	Source-specific identifiers

Skills follow the agentskills.io open standard. Source: Skills System.

Curator Defaults

Key	Default	Meaning
curator.enabled	true	Background maintenance of agent-created skills
curator.interval_hours	168	At most one run per 7 days
curator.min_idle_hours	2	Runs only after 2 h of inactivity
curator.stale_after_days	14	Unused skills become stale
curator.archive_after_days	30	Unused skills move to ~/.hermes/skills/.archive/
curator.consolidate	false	Opt-in LLM consolidation pass (typically 50-100 API calls)
curator.prune_builtins	false	Opt-in archival of unused bundled skills

Source: Curator.

Approvals and Authorization

approvals.* Keys

Key	Default	Meaning
mode	smart	smart (aux-LLM risk triage), manual (always prompt), off (same as --yolo)
timeout	300	Seconds to wait for a reply
cron_mode	deny	Cron behaviour on a dangerous command
single_query_mode	deny	One-shot -q behaviour
unattended_mode	deny	Webhook / API-server behaviour
deny	[]	User glob patterns blocked even under --yolo

A code-shipped hardline blocklist (for example rm -rf /, fork bombs, mkfs on the root device, dd to a disk) is enforced below all of these, with no override.

Gateway Authorization Order

1. Per-platform allow-all (for example DISCORD_ALLOW_ALL_USERS=true)
2. DM pairing approved list (hermes pairing approve <platform> <code>)
3. Platform allowlist (for example TELEGRAM_ALLOWED_USERS)
4. Global allowlist GATEWAY_ALLOWED_USERS
5. Global allow-all GATEWAY_ALLOW_ALL_USERS
6. Default: deny

Source: Security.

Network Ports and Endpoints

Service	Default bind	Auth
API server (OpenAI-compatible, /v1/chat/completions)	127.0.0.1:8642 (API_SERVER_HOST, API_SERVER_PORT)	API_SERVER_KEY required for every deployment, including loopback
Web dashboard (hermes dashboard)	127.0.0.1:9119	None on loopback; a non-loopback bind fails closed unless an auth provider (username/password or OAuth) is configured
Codex OAuth browser callback	localhost:1455	Only during hermes auth add openai-codex --browser

Sources: API Server, Web Dashboard.

Inference Providers

hermes model lists more than 40 providers. Main groups (as of 2026-09):

Group	Providers (provider id)
Subscription / OAuth	Nous Portal (nous, recommended; 300+ models + Tool Gateway), OpenAI Codex (openai-codex), GitHub Copilot (copilot, copilot-acp), Anthropic (anthropic, API key or Claude Max OAuth), xAI Grok OAuth, Qwen OAuth, MiniMax OAuth
Aggregators / gateways	OpenRouter, Vercel AI Gateway (ai-gateway), Ramp Router (router), Kilo Code, OpenCode Zen/Go, CommandCode, NovitaAI, Fireworks AI, Nebius Token Factory, GMI Cloud
Direct model labs	OpenAI API (openai-api), Google Gemini (gemini), DeepSeek, xAI (xai), z.ai/GLM (zai), Kimi/Moonshot, MiniMax, Qwen/Alibaba DashScope, Xiaomi MiMo, StepFun, Arcee, Tencent TokenHub/TokenPlan, Hugging Face
Cloud platforms	AWS Bedrock (bedrock), Google Vertex AI (vertex), Azure AI Foundry (azure-foundry), NVIDIA Build (nvidia)
Local / self-hosted	LM Studio (lmstudio), Ollama Cloud (ollama-cloud), any OpenAI-compatible custom endpoint (for example self-hosted Ollama or vLLM)

Three wire formats are used: chat_completions, codex_responses, anthropic_messages. Source: AI Providers.

Messaging Platforms

The gateway's platform table lists 28 targets (as of 2026-09): Telegram, Discord, Slack, Google Chat, WhatsApp (Baileys bridge), WhatsApp Cloud API, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, WeCom Callback, Weixin, BlueBubbles (iMessage), Photon (iMessage), QQ, Yuanbao, Microsoft Teams, LINE, ntfy, Raft, IRC, Buzz, SimpleX. Webhooks and the OpenAI-compatible API server are additional entry points. Source: Messaging Gateway.

Top-Level CLI Commands

Command	Purpose
hermes / hermes chat	Interactive chat (-q seeds a prompt; --oneshot answers and exits)
hermes setup (--portal)	Setup wizard; --portal does Nous OAuth + provider + Tool Gateway
hermes model / hermes fallback / hermes moa	Provider/model choice, fallback chain, Mixture-of-Agents presets
hermes auth	Credential and OAuth management (hermes login is deprecated)
hermes config	show, edit, get, set, unset, check, migrate, path, env-path
hermes gateway	run, start, stop, restart, status, list, install, setup, migrate
hermes skills / hermes bundles / hermes curator	Skill hub, bundles, background skill maintenance
hermes memory	External memory provider setup (setup, status, off)
hermes journey	Timeline of learned skills and memories (list, delete, edit)
hermes sessions	list, browse, export, prune, stats, optimize, repair
hermes cron / hermes kanban / hermes webhook	Scheduled jobs, multi-profile task board, event triggers
hermes mcp / hermes acp	MCP client config and MCP server mode; ACP server for editors
hermes plugins / hermes tools / hermes hooks	Plugins, per-platform toolsets, shell hooks
hermes profile	Isolated Hermes instances
hermes dashboard / hermes serve / hermes desktop	Web dashboard, headless backend, Electron desktop
hermes doctor / hermes dump / hermes logs / hermes status	Diagnostics
hermes backup / hermes import	Zip backup and restore of HERMES_HOME
hermes security audit / hermes approvals / hermes pairing	OSV supply-chain audit, approval history, DM pairing
hermes claw migrate / hermes import-agent	Import from OpenClaw, Claude Code, or Codex CLI
hermes update / hermes uninstall	Update source installs (channels main, stable, canary); remove

Source: CLI Commands Reference.

Self-Evolution Pipeline Facts

Item	Value
Repository	NousResearch/hermes-agent-self-evolution (MIT)
Engines	DSPy + GEPA (MIT); Darwinian Evolver (AGPL v3, external CLI only) for planned code evolution
Phase 1: skill files	Implemented
Phases 2-5: tool descriptions, system prompt sections, tool code, continuous loop	Planned
Cost	About $2-10 per optimization run (README)
Guardrails	Full pytest pass, skills <= 15 KB, tool descriptions <= 500 chars, no mid-conversation prompt changes, semantic preservation, human PR review
Research basis	GEPA paper, arXiv 2507.19457, ICLR 2026 Oral

Known Security Advisories

Hermes Agent has had multiple CVEs assigned in 2026. Most were published through VulDB-style disclosure and aggregated by CVE feeds; fixed versions are often not stated. Check the repository security page for the current list.

CVE	Affected (as published)	Component / issue
CVE-2026-7112	0.8.0	_check_auth in gateway/platforms/api_server.py: improper authentication (published 2026-04-27, moderate)
CVE-2026-7396	0.8.0	gateway/platforms/wecom.py
CVE-2026-9350	up to 2026.4.16	check_all_command_guards in tools/approval.py: missing authorization
CVE-2026-9368	up to 2026.4.16	execute_code in tools/code_execution_tool.py
CVE-2026-10548	up to 2026.4.23	_sync_anthropic_entry_from_credentials_file: local authentication bypass
CVE-2026-10223	not stated	_scan_memory_content: injection leading to code execution
CVE-2026-11461	up to 0.12.0	Session resolution: access to other users' sessions
CVE-2026-14628	up to 2026.5.16	extract_media in gateway/platforms/base.py: path traversal via webhook
CVE-2026-85105	0.18.0	session_id in _sess_nowait: authorization bypass
CVE-2026-85106	0.18.0	fetchLinkTitle: SSRF

Severity not independently verified

The affected ranges above come from the CVE descriptions. This page does not verify CVSS scores or fixed versions. Stay on the latest tag.

Cost Reference

Component	Cost	Basis
Software	Free (MIT)	LICENSE
Self-evolution run	~$2-10 per run	Self-evolution README
Hosting	"$5 VPS" is the project's own minimum example	README
LLM API usage	~$15-80/month typical	Community estimate (2026-04), unverified
Nous Portal subscription	TBD: pricing not published in the docs	Nous Portal
RetainDB memory provider	$20/month	Memory providers docs

Related Notes

• Hermes Agent Hub
• How-to Guides
• Explanation