Hermes Agent Guide (2026): MCP & Skills

Hermes Agent is the clearest example yet of an open-source AI agent that improves itself while you use it. Nous Research's own description is blunt: it is "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 project has pulled in 232,300 GitHub stars and 46,300 forks, and Nous Research was reportedly in talks to raise at least $75 million at a $1.5 billion valuation in July 2026.²³ For anyone running social accounts for a client or a brand, the practical question is simpler than the funding numbers: can you point this thing at your scheduler and trust it to behave. This guide covers what Hermes Agent is, how its MCP and skills system works, and the exact steps to connect it to posterly.

This is a long read (around 17 minutes). Every number carries a footnote, and where Nous Research's own documentation stops short of a claim we say so rather than guess. If you only want the connection steps, jump to Connect Hermes Agent to posterly.

What is Hermes Agent?

Hermes Agent is an open-source AI agent built by Nous Research, the AI lab founded in 2023 by Jeffrey Quesnelle, Karan Malhotra, Ryan (known as Teknium) and Shivani Mitra.⁴ It ships under the MIT license, and the project's homepage badges itself "Open Source, MIT License."⁵ The homepage tagline is "The Agent That Grows With You."⁵

Under the hood, Hermes is a Python 3.11+ project managed with uv, and Nous Research is explicit that it is "an independent Python project from Nous Research, not a fork of OpenClaw's TypeScript codebase," despite the two agents sharing a similar shape.⁶ Installation pulls in Python 3.11, Node 22, ripgrep and ffmpeg automatically, and code lives under ~/.hermes/hermes-agent/ with the executable at ~/.local/bin/hermes.⁷

Hermes reaches you through several surfaces at once:

• CLI, launched with hermes chat, the primary way most people use it day to day.⁸
• Native desktop app for macOS, Windows and Linux, described by third-party coverage as in public preview since June 2026.⁹
• Messaging gateway, which bridges Hermes into more than 30 chat platforms including Telegram, Discord, Slack, Google Chat, WhatsApp, WhatsApp Cloud API, Signal, SMS, email, Matrix, Microsoft Teams, LINE and Home Assistant, managed with hermes gateway setup.¹⁰
• IDE use, alongside the CLI, for coding-adjacent workflows.⁸

Install it with curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash on Linux, macOS, WSL2 or Termux, or the PowerShell equivalent on Windows; Docker and a best-effort Nix package are also available.⁷ After installation, the documented first commands are hermes model, hermes tools, hermes gateway setup, hermes setup --portal and hermes doctor.⁷

Name collision: Hermes Agent vs the Hermes models

Nous Research also publishes the Hermes model family (Hermes 3, Hermes 4), open-weight large language models released separately from the agent. Hermes 4 shipped in August 2025 as a family of Llama 3.1-based, hybrid-reasoning models at 14B, 70B and 405B parameters, and coverage described the release as models that "outperform ChatGPT without content restrictions."¹¹ Hermes Agent is not a wrapper around these models specifically; it is a model-agnostic agent that can point at Hermes models, or at Claude, GPT, Gemini, Grok, DeepSeek, GitHub Copilot models, AWS Bedrock, or a fully local model through Ollama, vLLM, SGLang or llama.cpp.¹² Read a Hermes headline carefully before assuming which product it is about.

Who is behind Hermes Agent, and what it costs

Nous Research was reportedly in talks for a new funding round of at least $75 million at a $1.5 billion valuation, led by Robot Ventures, on top of a prior total of $70 million raised, according to TechCrunch.² Hermes Agent itself is free and self-hosted. The paid layer is Nous Portal, described in Hermes's own docs as "Nous Research's unified subscription gateway and the recommended way to run Hermes Agent," giving "one OAuth login" across "300+ frontier agentic models."¹³⁵ TechCrunch reported Portal's paid tiers at "$20 to $200 monthly."² Nous Research's own pricing detail page returned an error when we checked it, so treat exact credit amounts per tier as secondary-sourced.¹⁴ Running Hermes against your own OpenRouter key, a different provider's key, or a fully local model needs no Portal subscription at all; you only pay whatever that provider charges.¹²

Key Hermes Agent statistics in 2026

Nous Research is private, so most of the following comes from the project's own repository, its documentation, and financial press coverage. Where a figure is only in a secondary source, this table says so.

A few adjacent claims appear only in secondary sources, so we flag them rather than repeat them as fact: a reported "110,000 stars in ten weeks" and an OpenRouter token-share lead over rival agent OpenClaw, both from independent comparison blogs.¹⁵ We also could not verify an exact launch date beyond secondary reporting pointing to late February 2026.¹⁶

How Hermes connects to tools: MCP, skills, cron and the gateway

Hermes reaches outside its own process in four documented ways, and they compose: a skill can call an MCP tool, a cron job can invoke a skill, and any of it can be delivered back to you through the gateway.

MCP, configured in YAML

The Model Context Protocol is the open standard that lets an AI client discover and call tools exposed by a server, over a local stdio process or a remote HTTP connection. Hermes implements it through a single configuration file, ~/.hermes/config.yaml, under the key mcp_servers. This is the detail most likely to trip people up coming from Claude Desktop or Codex, where the equivalent file is JSON: Hermes uses YAML, and the top-level key has an underscore.¹⁷

A stdio server (one Hermes launches itself, as a local process) looks like this:

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

A remote HTTP server, reached over the network instead of launched locally, looks like this:

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

Nous Research's guide walks through the same shape: edit the config, optionally run uv pip install -e ".[mcp]" inside the Hermes install directory if you need the MCP extras, start hermes chat, and ask "Tell me which MCP-backed tools are available right now" to confirm the server registered.¹⁸ After any config edit, run /reload-mcp inside a chat session rather than restarting the whole agent; set enabled: false on a server block to turn it off without deleting it.¹⁷ Registered tools appear namespaced as mcp_<server>_<tool>, and per-server options include timeout, connect_timeout, idle_timeout_seconds, max_lifetime_seconds, tools.include and tools.exclude glob filters, and mTLS client certificates for servers that require them.¹⁷ Hermes also ships a catalog picker (hermes mcp), plus hermes mcp install <name>, hermes mcp configure <name> and hermes mcp login <server> for OAuth-protected servers, and hermes mcp serve, which turns Hermes itself into an MCP server other tools can call.¹⁷

One documentation gap worth flagging: some third-party guides describe a hermes mcp add --url or --command flag for adding a server from the command line. We could not find that syntax in Nous Research's own documentation, which instead documents editing config.yaml by hand or using the catalog picker. Treat the flag-based syntax as unverified.

Skills: SKILL.md, installed from GitHub or a URL

A Hermes skill is a folder containing a SKILL.md file with YAML frontmatter: name, description, version, plus Hermes-specific metadata.hermes.tags and metadata.hermes.category, with optional fields for supported platforms and tool requirements.¹⁹ Skills live under ~/.hermes/skills/<category>/<skill>/ by default, described in the docs as "the primary directory and source of truth," with additional directories configurable through skills.external_dirs.¹⁹

Install commands documented by Nous Research cover several sources:¹⁹

hermes skills install openai/skills/k8s          # GitHub owner/repo/path
hermes skills install official/security/1password # official skills
hermes skills install https://example.com/SKILL.md # direct URL to a SKILL.md
hermes skills search <query> --source skills-sh
hermes skills browse --source official

A skill runs by name inside a chat session as /<skill-name> [instruction]. Hermes can also author its own skills through a skill_manage tool, and if skills.write_approval: true is set, self-authored skills are staged in ~/.hermes/pending/skills/ for you to review before they take effect.¹⁹ posterly's own public SKILL.md-style skill lives at github.com/awpthorp/posterly-agent, a GitHub-hosted skill you can install the same way, with either the owner/repo/path form or a direct URL to its SKILL.md.

Cron and delivery

Hermes accepts natural-language scheduling through /cron add inside a chat session, or hermes cron create from the shell. The documentation is specific about what a scheduled run actually sees: "Cron jobs run in a completely fresh agent session. The prompt must contain everything the agent needs that is not already provided by attached skills."²⁰ The gateway checks for due jobs every 60 seconds, jobs persist in ~/.hermes/cron/jobs.json, and results can be delivered to telegram, discord, slack, a specific platform:chat_id, or all connected surfaces at once.²⁰

Subagents and sandboxing

For larger jobs, Hermes supports delegate_task, which spins up a subagent with fresh context and its own terminal; by default up to three children run concurrently, optionally isolated in its own git worktree.²¹ Terminal execution can run locally or sandboxed through Docker, SSH, Singularity, Modal, Daytona or Vercel Sandbox, with the Docker backend hardened by dropped capabilities, no-new-privileges and a process limit of 256.²²

Connect Hermes to posterly

posterly ships one MCP server with two transports: a local stdio package on npm, and a hosted HTTP endpoint. Hermes can use either, because it runs on your own machine or your own server rather than a locked-down cloud sandbox. The canonical setup pages are posterly's Hermes page, the MCP page, and the MCP docs; this section maps that same setup onto Hermes's YAML config.

Step 1: turn on API access in posterly

Sign up for any posterly plan, then open Dashboard, then API and MCP and enable the API and MCP add-on. It costs $3 a month on top of any plan; the Agency API tier is $29 a month. Click "Create Key" and copy the bearer key, which starts with pst_live_. If you would rather have an agent handle signup itself, the agents signup page covers that path, described in more depth in how AI agents sign users up to SaaS.

Step 2: add posterly to config.yaml

For a local install where Hermes can run npx itself, add posterly as a stdio server:

mcp_servers:
  posterly:
    command: "npx"
    args: ["-y", "posterly-mcp-server@latest"]
    env:
      POSTERLY_API_KEY: "pst_live_your_key_here"

Following Nous Research's own guidance to keep secrets in .env, put the real key in ~/.hermes/.env instead of the config file, either by hand or with hermes config set POSTERLY_API_KEY pst_live_your_key_here, then reference it with substitution:²³

mcp_servers:
  posterly:
    command: "npx"
    args: ["-y", "posterly-mcp-server@latest"]
    env:
      POSTERLY_API_KEY: "${POSTERLY_API_KEY}"

If you would rather point Hermes at posterly's hosted endpoint instead of running the npm package locally, use the HTTP form:

mcp_servers:
  posterly:
    url: "https://www.poster.ly/api/mcp"
    headers:
      Authorization: "Bearer pst_live_your_key_here"

Both forms are documented shapes for Hermes's mcp_servers block: command/args/env for stdio, url/headers for HTTP.¹⁷ The local stdio route exposes all 78 tools (the 75 hosted tools plus posterly's public setup and signup tools) and can hand files straight to upload_media; the hosted route is JSON-only and a better fit if you are running Hermes somewhere that should not shell out to npx.

Step 3: reload and verify

Start hermes chat if it is not already running, then run /reload-mcp to pick up the new server. Ask Hermes: "which MCP-backed tools are available right now?" and confirm mcp_posterly_whoami and mcp_posterly_list_accounts appear.¹⁸ Then run a read-only check: "using the posterly MCP server, call whoami and then list_accounts." A 401 means the key is wrong; a 403 with insufficient_subscription means the API and MCP add-on is not active on your plan. Discovery metadata also lives at https://www.poster.ly/.well-known/mcp/server-card.json if you want Hermes to confirm the transport and tool list on its own.

Step 4 (optional): install the posterly skill

If you would rather give Hermes a written playbook alongside the raw MCP tools, install posterly's GitHub-hosted skill:

hermes skills install awpthorp/posterly-agent
# or, using the direct SKILL.md URL form documented by Nous Research
hermes skills install https://raw.githubusercontent.com/awpthorp/posterly-agent/main/SKILL.md

The skill encodes the same order of operations posterly recommends everywhere: prefer MCP when it is available, confirm the account, caption, media and schedule with you before anything publishes, and fall back to the REST API only when MCP is not reachable.

What you can automate

Once posterly is registered as an MCP server, prompts to Hermes read like plain instructions rather than code. Eight workflows we see teams build once posterly and Hermes are connected, each mapped to a posterly tool:

1. Schedule a week of posts. "Draft five LinkedIn posts from this product update, use generate_captions for the copy, find_available_slot for each, and create_post once I approve." Turn it into a /cron add job that drafts a fresh batch every Friday.

2. Repurpose a blog post across platforms. "Produce native versions of this article for X, Threads, Bluesky, Mastodon and Facebook, then schedule them across Tuesday and Thursday." create_posts_batch handles up to 25 posts in one confirmed request.

3. Pull analytics into a weekly summary. "Call get_account_analytics for Instagram and LinkedIn over the last 30 days and tell me which format grew reach." Deliver the result to Slack or Telegram through the gateway.

4. Upload media and schedule it in one pass. "Upload this video with upload_media, write a caption, and schedule it for Friday morning." The stdio route runs on your own machine, so Hermes can hand it a local file path directly.

5. Draft replies to Google Business reviews. "List new reviews, draft replies with suggest_google_business_review_reply, and show me the drafts." Nothing publishes until you say so.

6. Run a Monday content gap check as a cron job. "Every Monday at 9am, check list_posts for gaps this week and message me three ideas on Telegram." This mirrors a documented Hermes user story: a scheduled job that summarizes and posts to a chat platform every weekday morning.²⁴

7. Delegate a content refresh to a subagent. "Delegate: audit our last 20 posts with get_post_analytics, then propose a new posting schedule." delegate_task gives the subagent a fresh context window without cluttering the main chat.²¹

8. Validate before anything goes live. validate_post checks a payload against a platform's rules without spending quota, which matters most on a cron job or subagent that might retry on its own schedule while you are not watching.

Hermes vs OpenClaw vs Claude Code vs Codex

Hermes and OpenClaw sit closest together: both are free, self-hosted, MIT-licensed agents that run local stdio MCP servers, remote HTTP servers, and the same SKILL.md format, and Firecrawl's comparison notes Hermes "is an independent Python project from Nous Research, not a fork of OpenClaw's TypeScript codebase," even though the two look similar from the outside.⁶ Claude Code and Codex are the proprietary alternative: both add MCP servers with a first-party CLI command into a config file scoped to a subscription, not a config you own outright. Read the full Claude guide for the Claude Code walkthrough. posterly also has dedicated pages for OpenClaw, Poke, which lives inside a messaging app rather than a terminal, and the posterly CLI for scripting outside any agent, all authenticating with the same key against the same MCP endpoint.

Limits, security and gotchas

Tool calling has to be native. Nous Research's docs are direct: "Without tool calling enabled, the model will try to call tools by writing JSON in its response text, but Hermes won't recognize it." Pick a model that supports native tool calling, whether through Nous Portal, a hosted provider, or a local model server.¹²

Local models need real hardware. The default Ollama context window of 2,048 tokens "is too small for agentic work," and Nous Research suggests roughly 32GB of RAM or 16 to 24GB of VRAM for a usable local setup.²⁷

Platform support has tiers. Tier 1 covers macOS on Apple Silicon, Windows 10/11 (some features unavailable), Linux and WSL2, and Docker (hermes update does not work inside Docker). Tier 2 covers Termux and Nix. Intel macOS, PyPI installs, Homebrew and AUR are unsupported.²⁸

Security modes are configurable, not fixed. Hermes documents smart, manual and off approval modes, plus a YOLO mode (--yolo, /yolo, or HERMES_YOLO_MODE=1) that "disables all dangerous command safety checks for the session, except the hardline blocklist." Gateway connections use DM pairing codes and allowlists to control who can message a Hermes instance.²⁹

Real CVEs have been found and fixed. The Cloud Security Alliance published a research note on three vulnerabilities: a path-traversal bug in the WeChat Work gateway, a symlink-following issue fixed in v0.9.0, and a WebUI path-traversal bug. The same note flags the skill marketplace as a supply-chain risk: "The skill marketplace represents a supply chain risk analogous to package registries in traditional software development but with compounded consequences," so review a third-party skill's contents before installing it, the same way you would review an unfamiliar npm package.³⁰ Open GitHub issues also track gaps in skill and prompt-injection scanning.³¹

Environment variables are not passed through by default. "Hermes does not blindly pass your full shell environment. Only explicitly configured env plus a safe baseline are passed through" to an MCP server, which limits what a misconfigured stdio server can accidentally read from your shell.¹⁷

posterly-side limits. Create-post calls are capped at 100 requests per hour per key, with separate limits for media uploads and read calls; create_posts_batch bundles up to 25 posts per request. API keys carry scopes such as posts:write, and a key scoped to one workspace cannot touch another. The hosted upload_media tool accepts base64 payloads up to roughly 5MB decoded; for larger video, prefer the local stdio route, which can hand Hermes a file path directly, or upload_media_from_url.

Best for, not best for

Hermes Agent plus posterly is well-suited for

• Developers and agencies comfortable owning their own infrastructure, since Hermes is self-hosted and free beyond whatever model you point it at
• Teams that want an agent reachable from Telegram, Discord or Slack, using Hermes's gateway rather than a bespoke integration for each platform
• Workflows that benefit from a real learning loop, where Hermes writes and refines its own skills for recurring publishing tasks over time
• Anyone who wants full model choice, from a Nous Portal subscription down to a fully local, offline model

Hermes Agent is not the best fit for

• Teams that want a managed, no-install experience, since setup means a terminal, a config file and, for local models, real hardware; see Poke for a text-message-only alternative
• Anyone who needs a JSON config file to match an existing Claude Desktop or Codex setup, since Hermes's YAML shape and underscore key (mcp_servers) are genuinely different and will not paste in directly
• Workflows where installing third-party skills from unknown sources is a hard no, given the CSA's supply-chain warning on the skill marketplace
• Windows users who need every feature, since Nous Research's own docs note some features are unavailable on Windows today

Final word

Hermes Agent is what happens when an open-source lab builds the agent it wants to run itself: self-hosted, model-agnostic, reachable from a dozen chat apps, and willing to write and refine its own skills over time. That flexibility comes with a YAML config to learn and a skill ecosystem worth reading before you trust it, but for a team that already runs its own infrastructure, it is one of the more capable free options available. Connected to posterly, Hermes reaches the same 75 hosted tools and 18 platforms every other agent in this series does, over whichever transport fits how you deployed it.

Start on posterly's Hermes page or the agents signup page, add the posterly block to ~/.hermes/config.yaml, and ask Hermes to draft and schedule your first week of posts before you hand a cron job the keys.

Footnotes