Welcome.

Hermes Agent is not a chat app. It is an autonomous AI agent that learns, remembers, and operates wherever you put it — a laptop, a $5 VPS, a serverless container, your Telegram inbox. This guide takes you from never having heard of it to running it like a professional.

You may have seen it labelled Poseidon Agent. Poseidon is a skin (a visual theme) on top of Hermes. The engine, the commands, the configuration, the skills — all identical. Anything you learn here applies to both. Throughout this guide we call it Hermes.

The guide is written for someone who has used Claude or ChatGPT before but never installed a real agent on their own machine. Every term that might be new is explained on first use. You can also flip to the glossary on page 7 anytime.

How this guide is structured

Sixteen parts, each one a self-contained section. Start at the beginning if you are new. Skip ahead if you know the basics and want a specific feature. A printable cheat sheet sits on the last page.

Part 1 — Foundations. What Hermes is, who made it, the vocabulary.
Part 2 — Installation. The one-liner that does everything.
Part 3 — The TUI. The screen you see when you launch it.
Part 4 — Authentication & providers. Connecting it to a model.
Part 5 — Slash commands. Every command, organised.
Part 6 — Tools. The agent's hands and eyes.
Part 7 — Skills. The agent's procedural memory.
Part 8 — Memory & personality.
Part 9 — Gateway. Telegram, Discord, Slack, and the rest.
Part 10 — Cron & Kanban. Scheduled and parallel work.
Part 11 — Computer use.
Part 12 — MCP servers.
Part 13 — Build your own skill.
Part 14 — Config reference.
Part 15 — Debugging.
Part 16 — Mastery patterns and the cheat sheet.

What is Hermes Agent?

An autonomous AI agent. Not a chatbot, not a plugin, not a coding copilot. Something different in kind.

Most AI tools you have used are assistants — they wait for you to type, they answer, they wait again. Hermes is an agent. You give it a goal. It plans. It uses tools. It hits errors and figures out workarounds. It comes back when the job is done, or it asks you a question if it genuinely cannot decide.

What makes it different from ChatGPT or Claude

ChatGPT and Claude are language models with a chat interface bolted on. Hermes is an open agent runtime that wraps any language model and gives it a body — file system access, a browser, a terminal, a memory store, a messaging gateway, a scheduler. You pick the brain (any model), Hermes provides the rest.

What makes it different from a regular AI app

1. It learns. Every session feeds a memory store. Useful patterns become skills. Skills get refined automatically by a background process called the Curator.
2. It lives outside your laptop. Same Hermes runs on a phone via Telegram, on a server, in a Docker container, on a serverless platform. One agent, many surfaces.
3. It is open. The full source is on GitHub. The skill format is an open standard. You can run it offline against a local model if you want.
4. It is fast. Tool calls happen in milliseconds. You feel the difference within a session — there is no lag between deciding to act and the action happening.

Who built it

Nous Research. The same team behind the Hermes language model series, Nomos, and Psyche. They train models for a living, so the agent's prompting, tool design, and memory handling all come from people who know how language models actually behave under load.

The Poseidon question

Poseidon Agent is a visual skin. The big POSEIDON-AGENT banner you see in the terminal is one of several available "skins" the project ships. Underneath, it is the same Hermes engine. Change the skin with /skin. That is the only difference.

Glossary

Every term that appears later. Read once, refer back any time.

Prerequisites

The shortest possible list. The installer handles almost everything.

All platforms — one requirement only

Git. Run git --version in your terminal. If you see a version number, you are ready. If not:

• macOS — open Terminal and run xcode-select --install. macOS will prompt for the developer tools, which include Git.
• Linux — your distro's package manager: sudo apt install git (Ubuntu/Debian), sudo dnf install git (Fedora), sudo pacman -S git (Arch).
• Windows — the Hermes installer ships a portable Git automatically. You do not need to install Git separately.

What the installer handles for you

You do not need to install any of the following. The installer will detect what is missing and add it.

Disk space

Plan for around 1.5 GB for the install (Python venv, Node modules, Chromium). The data directory grows from there as you use it — memory, sessions, skills.

Install on macOS & Linux

One command. Sixty to one hundred and twenty seconds depending on your network.

The one-liner

Open Terminal. Paste this. Press Enter.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

What just happened

1. The installer detected your OS (macOS or Linux).
2. It cloned the Hermes repo to ~/.hermes/hermes-agent/.
3. It used uv to install Python 3.11 into a private virtualenv.
4. It installed Node.js, ripgrep, and ffmpeg if you didn't already have them.
5. It downloaded Chromium for the browser tool.
6. It placed a launcher at ~/.local/bin/hermes and added it to your PATH.

Reload your shell

The installer modifies your shell config (.zshrc or .bashrc) to add ~/.local/bin to PATH. Either close and reopen the terminal, or run:

source ~/.zshrc    # macOS default + most Linux
source ~/.bashrc   # Ubuntu/Debian default

Verify the install

hermes --version
hermes doctor

--version prints the installed Hermes version. hermes doctor runs a system check and tells you about any missing pieces. A clean doctor output means you are ready.

First launch

hermes

This drops you into the TUI — the terminal user interface you saw on the cover. On first launch, Hermes will walk you through choosing a model provider (next section).

Where things live

Install on Windows & Android

Native Windows is in early beta. The smoothest Windows path is still WSL2.

Windows — WSL2 (recommended)

Windows Subsystem for Linux. Microsoft-made. Lets you run a real Linux environment inside Windows. If you have not used it before:

1. Open PowerShell as administrator.
2. Run wsl --install. This installs Ubuntu by default.
3. Restart your computer when prompted.
4. Open the new Ubuntu app from the Start menu. Create a Linux username/password.
5. Run the macOS/Linux one-liner from the previous page inside the Ubuntu terminal.

Windows — native PowerShell (early beta)

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

The native installer handles Python, Node.js, ripgrep, ffmpeg, and a portable Git that won't conflict with any existing Git install. Code lands at %LOCALAPPDATA%\hermes\hermes-agent\. The hermes command is added to your user PATH.

Restart your terminal after install so PATH picks up. Then run hermes in a fresh PowerShell window.

What works natively on Windows

• CLI (hermes, hermes setup, hermes gateway) — full support
• Gateway (Telegram, Discord, Slack, etc.) — full support, runs as a background PowerShell process
• Cron scheduler — full support
• Browser tool — full support (Chromium via Node.js)
• MCP servers — full support, both stdio and HTTP transports

What requires WSL2

The dashboard's embedded terminal pane is WSL2-only. The rest of the dashboard works natively.

Android via Termux

Install Termux from F-Droid (the Play Store version is outdated). Open Termux. Run:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer detects Termux automatically. It uses Termux's pkg manager for system dependencies, sets up the venv, and skips the browser bootstrap by default (Chromium does not run well on phone hardware). You can then use Hermes as a CLI agent on your phone, or run a Telegram bot from your phone.

Your first launch

What happens after you type hermes for the first time.

The setup wizard

First launch triggers hermes setup automatically. The wizard asks four things:

1. Which model provider — Nous Portal (recommended), OpenRouter, OpenAI, Anthropic, x.ai, or a custom endpoint.
2. Your API key for that provider. Pasted in once, saved to ~/.hermes/.env with 600 permissions.
3. Which model to use by default. The wizard fetches the available list from the provider.
4. Which tools to enable. Default selection is fine; you can change it later with hermes tools.

The Nous Portal shortcut

If you want one subscription that covers 300+ models plus the Tool Gateway (web search, image generation, TTS, cloud browser) without juggling per-tool API keys:

hermes setup --portal

This logs you into Nous Portal in your browser, sets it as your provider, and turns on the Tool Gateway in one command. Recommended for beginners.

After setup completes

You land in the TUI. You see a banner (Poseidon by default), a list of available tools, a list of available skills, and a prompt at the bottom waiting for you to type.

Try this as your first message:

What can you do?

Hermes will introduce itself, list its capabilities, and suggest a few sample tasks to try. From here, anything goes.

Reconfiguring later

The TUI explained

TUI = Terminal User Interface. The screen you see after typing hermes.

Top — the banner

The big ASCII wordmark (POSEIDON-AGENT by default). Purely cosmetic. Change it with /skin. Options include poseidon, hermes, minimal, and others.

Below the banner — the info panel

A bordered box that lists:

• Hermes Agent version — current installed version and upstream commit hash.
• Available Tools — every tool Hermes can call this session. Coloured turquoise.
• Available Skills — every skill installed, grouped by category. Loaded on demand by the agent.
• Tool + skill counts — the total at the bottom (e.g. "30 tools · 90 skills").
• Update warning — if you are behind on commits, you see an orange warning telling you to run hermes update.

To the left of the box, an ASCII art glyph (a stylised Ψ or similar) and three lines of metadata: the model name, the provider, the working directory, and the session ID. The metadata is how you confirm which model is actually answering and which session you are in.

Bottom — the status bar

A single horizontal line containing:

The input box

At the very bottom. You type here. Type / to open an autocomplete menu of all available slash commands. Press Enter to submit. Press Ctrl+C to interrupt the running agent.

Pinned panels (left side)

Small tags below the input — /remote-control, File explorer, Rich Input. Each opens a sidebar panel. The file explorer shows your working directory as a tree. Rich Input gives you a multi-line editor for long prompts.

Choosing a provider

Hermes is provider-agnostic. You bring the brain; it provides everything else.

The shortest path — Nous Portal

One subscription covers 300+ models from every major provider plus a Tool Gateway (web search, image gen, TTS, cloud browser). Recommended unless you have a strong reason to pick one provider directly.

hermes setup --portal

If you want to pick a specific provider

What gets saved where

Your API key goes into ~/.hermes/.env with mode 600 (only you can read it). The current provider + model selection live in ~/.hermes/config.yaml under the model: key.

Switching models mid-session

/model claude-sonnet-4
/model anthropic:claude-opus-4
/model x-ai:grok-4
/model custom:qwen3-coder:30b

Switches are session-only by default. Add --global to persist to config.yaml. To add a brand-new provider, you must exit the TUI and run hermes model from your terminal.

Model aliases — pick a name you'll remember

hermes config set model.aliases.fav anthropic/claude-opus-4
hermes config set model.aliases.grok x-ai/grok-4
hermes config set model.aliases.fast openai/gpt-5-mini

Then in chat: /model fav, /model grok, /model fast. Much faster than remembering exact model strings.

Slash commands — Session

Type / in the input box to open the autocomplete menu. Built-in commands are case-insensitive.

Session commands — continued

Slash commands — Configuration

Tune the agent's behaviour, voice, model, and display in-session.

Slash commands — Tools & Skills

Control the capabilities Hermes has access to inside a session.

Slash commands — Info & Exit

Diagnostics, attachments, exit. The rest of the reference.

Messaging-only commands

These work inside Telegram, Discord, Slack, and other messaging platforms — not in the CLI:

Dynamic skill commands

Every installed skill becomes a slash command. Examples: /gif-search, /github-pr-workflow, /excalidraw, /spotify, /obsidian. Type / and scroll the autocomplete to see them all.

Tools — how they work

A tool is one thing the agent can do. Read a file. Click a button. Send a message. Run a shell command. There are 70+ built into Hermes.

Tools vs toolsets

A toolset is a named group of related tools. The browser toolset bundles browser_click, browser_back, browser_fill, etc. You enable or disable toolsets in hermes tools — every individual tool inside the set turns on or off together.

The 30 built-in toolsets

And ten more: slack, signal, matrix, whatsapp, email, sms, voice, audio_gen, datastore, plus a handful of platform-specific bridges. Run /toolsets in your TUI to see the live list.

Enabling / disabling

hermes tools                  # interactive toggle UI
/tools disable browser-cdp    # turn off one toolset for the session
/tools enable computer_use    # re-enable

Skills — the procedural layer

A skill is a reusable procedure stored as a markdown file. It knows when to trigger and what steps to run.

How skills differ from tools

Tools are atomic — one operation, like "click this button" or "read this file." Skills are recipes — a sequence of tool calls plus instructions on when to use them. A skill says "when the user asks for a viral tweet, gather these inputs, apply this template, return this format."

How they activate

Two ways. Implicitly — Hermes detects a trigger phrase in your message ("write me a viral tweet") and loads the matching skill automatically. Explicitly — you type /skill-name as a slash command.

The skill format

---
name: viral-tweet-generator
description: Generate viral X/Twitter tweets using 9 proven patterns.
                Trigger: "viral tweet", "write a tweet".
metadata:
  tags: twitter, marketing, viral
---

## When to use
Trigger whenever the user asks for tweet copy that needs to perform.

## Instructions
1. Identify the angle (hot take, list, contrarian, etc.)
2. Apply one of the 9 patterns from the appendix
3. Return three variants, ranked
...

Where skills live

~/.hermes/skills/ — every subdirectory is a category. Inside each category, every subdirectory is a skill containing at minimum a SKILL.md. Hermes scans this tree on boot and after /reload-skills.

The 24 default categories

Apple, autonomous-ai-agents, creative, data-science, devops, diagramming, dogfood, domain, email, gaming, gifs, github, inference-sh, mcp, media, mlops, note-taking, productivity, red-teaming, research, smart-home, social-media, software-development, yuanbao.

Browsing the catalog

/skills              # open the interactive browser
/skills list         # list installed
/skills search ocr   # search the online hub
/skills install <name>  # add one to your install
/skills publish      # share your own to the hub

The Skills Hub

agentskills.io — the public registry. Open-standard format means skills built for Hermes work on other agents too. You can pull community skills, publish your own, and version them like any other open-source package.

Skills — by category

Each category is a folder of related skills. Here is what each one covers.

Skill categories — continued

Loading a skill on demand

Installed skills aren't always loaded — Hermes loads them when triggered to keep the context lean. You can force-load by name: /skill-name. Pre-load multiple at once via skills.always_load in config.yaml.

Discovering skills you don't have

/skills search ocr        # search the hub
/skills install <name>    # add one
/skills publish my-skill  # share your own

Memory — how it works

Most AI tools forget you between sessions. Hermes does not.

The two memory layers

1. Working memory — the active conversation in front of the model. Bounded by the model's context window. Auto-compresses when it grows past the threshold.
2. Long-term memory — SQLite database at ~/.hermes/memory.db. Uses FTS5 (full-text search version 5) to find relevant past memories quickly. Survives forever.

What gets remembered

Not the entire conversation. That would balloon the database. Hermes triggers memory writes when:

• A piece of information is repeated across sessions
• You explicitly say "remember this"
• The agent's nudge system decides something is important (a fact about you, a preference, a recurring workflow)
• A skill is created or improved during use

How recall works

At the start of each turn, Hermes runs a fast FTS5 search over your memory store using your message as the query. Relevant memories are summarised by a small LLM call and injected into the prompt. You don't see this happen — it just feels like Hermes remembers things.

Honcho — the user model

Honcho is a Plastic Labs library Hermes uses to build a dialectic model of who you are over time. It is not the same as memory. Memory is facts and events; Honcho is the meta-model — your communication style, your interests, your goals, your boundaries.

Inspecting memory

hermes memory list           # show recent entries
hermes memory search <query> # FTS5 search
hermes memory clear          # nuke everything (asks twice)
hermes memory export         # dump to JSON

Privacy

Memory is local. The database file is on your disk. Nothing leaves your machine unless you actively send it (e.g. asking Hermes to upload a debug report). If you are sensitive about a particular conversation, use /exit --delete to permanently remove that session's history before exiting.

Personality & SOUL.md

Hermes ships with a default voice. You can replace it entirely.

SOUL.md — the personality file

A markdown file at ~/.hermes/SOUL.md. Loaded into every prompt as the agent's character sheet. Defines how Hermes talks, what its priorities are, what it refuses to do.

Example SOUL.md:

# SOUL

You are Hermes. You operate for Pavel.

## Voice
Direct. No filler. Fragments OK. Confidence over hedging.

## Priorities
1. Be useful, not impressive
2. Ask one clarifying question, never three
3. Save work to files when the output is long

## Refusals
- Never execute trades or send money
- Never modify files outside ~/projects without explicit consent
- Confirm before destructive shell commands

Switching personalities mid-session

/personality formal
/personality casual
/personality terse
/personality <custom-name>

Each named personality is a separate SOUL-style file in ~/.hermes/personalities/. Create as many as you want.

Context files — per-project soul

SOUL.md is global. Context files are project-scoped. A file named HERMES.md in any working directory gets injected into prompts that run from that directory. Use it to tell Hermes about a specific codebase, brand, or client.

# HERMES.md (inside ~/projects/acme-co)

This project is the Acme website rebuild.
- Tech stack: Next.js 15, Tailwind, Vercel
- Brand voice: confident, blue-collar, no jargon
- Always run `pnpm test` before committing

Curator — the background groomer

Curator is a background process that keeps your skills library healthy. It improves skills based on how they get used, deduplicates near-identical ones, and archives skills you haven't touched in months.

/curator status   # see what it's been up to
/curator run      # trigger an immediate pass
/curator pin <skill>     # protect from archival
/curator archive <skill> # manually retire

The gateway — what it is

A separate Hermes process whose only job is to bridge messaging platforms to your agent.

Why a separate process

Three reasons:

1. Always-on. The gateway runs in the background as a launchd / systemd service. You can close your CLI; the bots keep working.
2. Multi-platform. One gateway handles every platform simultaneously. Adding Telegram doesn't disrupt your Discord bot.
3. Stable. The gateway restarts itself on crashes. Your message history is unaffected by CLI session changes.

Setting it up

hermes gateway setup   # interactive wizard
hermes gateway start   # start the background service
hermes gateway stop    # stop it
hermes gateway restart # bounce it (e.g. after config change)
hermes gateway status  # is it running? which platforms?
hermes gateway run     # run in foreground (for debugging)

Platforms supported (20+)

Telegram — step by step

The fastest path to a personal Hermes bot you can talk to from anywhere.

1. Create a bot via BotFather

1. Open Telegram, search for @BotFather, start a chat.
2. Send /newbot.
3. Pick a display name (e.g. "Hermes").
4. Pick a username ending in bot (e.g. my_hermes_bot).
5. BotFather replies with an HTTP API token. Save it.

2. Get your Telegram user ID

Open Telegram, search for @userinfobot, start the chat. It instantly replies with your numeric ID (e.g. 693685626). Save it.

3. Start a chat with your new bot

Open the bot you just made. Press Start. This is required — Telegram bots cannot DM users who haven't initiated.

4. Configure Hermes

Open ~/.hermes/.env in any editor and add:

TELEGRAM_BOT_TOKEN=<your-token-from-step-1>
TELEGRAM_ALLOWED_USERS=<your-user-id-from-step-2>
TELEGRAM_HOME_CHANNEL=<your-user-id-from-step-2>

5. Start the gateway

hermes gateway start
hermes gateway status

Status should show Telegram as running. Open Telegram, send any message to your bot. Hermes replies within seconds.

Streaming word-by-word

Hermes can stream its replies token-by-token, editing the same message live as it generates. Edit ~/.hermes/config.yaml and find the streaming: section:

streaming:
  enabled: true
  transport: edit
  edit_interval: 0.3        # 300ms between edits
  buffer_threshold: 6       # update every 6 new chars
  cursor: " ▉"              # blinking cursor while generating
  fresh_final_after_seconds: 60.0

Restart the gateway: hermes gateway restart. From now on, Telegram replies build up word-by-word with a turquoise cursor at the end.

Other useful Telegram env vars

Cron — scheduled automations

Tell Hermes to do something at a recurring time. Every morning, every Friday, every five minutes.

A first example

Inside the TUI:

/cron add "every morning at 8am" "Summarise overnight emails and send to my Telegram"

Plain-English schedules. No need to learn crontab syntax — Hermes parses common patterns automatically. You can also use traditional cron expressions if you prefer (0 8 * * *).

Managing scheduled tasks

/cron list                # show all scheduled tasks
/cron pause <id>          # temporarily disable
/cron resume <id>         # re-enable
/cron run <id>            # run it now, manually
/cron edit <id>           # change schedule or prompt
/cron remove <id>         # delete it

Where deliveries land

Cron deliveries go to the home channel of whichever platform you set. For Telegram, that's the chat ID in TELEGRAM_HOME_CHANNEL. You can mark any chat as home by sending /sethome in that chat.

Realistic scheduled-task examples

• Every morning at 7am — summarise overnight Telegram messages and DM the digest
• Every Friday at 5pm — generate a one-paragraph weekly review from this week's sessions
• Every 4 hours — check GitHub PRs assigned to me, ping if any are stale
• Every Monday — draft the week's content calendar and post it to my Notion
• Every day at 6pm — read my unread email, draft replies, save to drafts folder

Kanban — parallel work

A built-in task board. Multi-profile, multi-project. Drive it from chat, the CLI, or both at once.

The mental model

A Kanban board has tasks. Each task has a status (backlog, in progress, blocked, done), an assignee (a user or a subagent), comments, and dependencies. Hermes can coordinate work across many tasks simultaneously — kicking off subagents in parallel, gathering results, marking complete.

Basic usage

/kanban list                       # show all open tasks
/kanban create "title here"        # add a task
/kanban show t_abc                 # task details
/kanban comment t_abc "update"     # annotate
/kanban unblock t_abc              # clear a blocker
/kanban dispatch                   # assign next task to a worker

Multi-board support

/kanban boards list
/kanban boards create <slug>
/kanban boards switch <slug>
/kanban --board <slug> <action>

Use separate boards per project. One for client work, one for personal, one per major feature.

Worker lanes

A worker lane is a subagent that auto-picks tasks from the board. Configure them in config.yaml under kanban.workers. Each worker has a name, a model, and an optional skill or tool restriction. Tasks get dispatched based on assignee match.

Auto-subscribe

When you create a task from a chat (Telegram, Discord, etc), that chat auto-subscribes to the task's terminal events. You get a notification when it's done, blocked, or commented on.

Why this matters

Without Kanban, you talk to Hermes one task at a time. With Kanban, you can hand it a queue of ten things and let it work them in parallel — limited only by your token budget and which model you're using.

Computer use

Hermes takes screenshots of your screen, moves the cursor, types, clicks. Real autonomy on a real desktop.

Enabling it

hermes tools                # interactive UI
# Enable: computer_use

On first call, macOS will prompt you to grant Accessibility and Screen Recording permissions to the Hermes process. Approve both in System Settings → Privacy & Security. Linux uses xdotool (X11) or wlrctl (Wayland) under the hood.

What it can do

• Take screenshots and analyse them with vision
• Move the cursor to specific coordinates
• Left-click, right-click, double-click, triple-click
• Click and drag
• Type text and key combinations (⌘+C, ⌘+V, Cmd+Tab)
• Scroll, zoom, switch applications
• Read and write the system clipboard

What it cannot do (intentionally)

• Execute trades, send money, initiate financial transfers
• Type into browsers (use the browser toolset instead — DOM-aware, much faster)
• Type into IDEs or terminals (use the terminal toolset instead)
• Take destructive actions without confirmation

Safety by default

Hermes screenshots before most actions and shows you what it's about to do. For genuinely destructive actions (deleting files, sending messages, closing apps with unsaved work), it asks for confirmation. You can pre-approve with /approve session (this session only) or /approve always (permanent allowlist).

When to actually use it

Use computer_use only when no other tool can do the job. Filling a form in a native app, dragging files in Finder, configuring system settings, screen-recording a workflow. Always prefer the more specialised toolsets first (browser, terminal, filesystem) — they are faster, more reliable, and don't depend on visual recognition.

MCP — Model Context Protocol

An open standard for connecting external tools and data sources to AI agents.

What MCP is, plainly

Before MCP, every AI tool had its own way of plugging in external capabilities. Each provider built their own plugin format. None of it was interoperable. MCP is the open standard that fixes this — built by Anthropic and adopted broadly.

An MCP server is a small program that speaks a defined protocol. It exposes tools, resources, and prompts. Any MCP-aware agent (including Hermes) can connect to it and use those capabilities. There are hundreds of MCP servers already published: GitHub, GitLab, Stripe, Postgres, Slack, Notion, Linear, Brave Search, Puppeteer, and many more.

Adding an MCP server to Hermes

hermes mcp add <name> \
  --command "<cmd>" \
  --args "<arg1> <arg2>"

Example — adding the GitHub MCP server:

hermes mcp add github \
  --command "npx" \
  --args "@modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=<your-token>

Listing what's installed

hermes mcp list
hermes mcp remove <name>
hermes mcp inspect <name>    # see exposed tools

Reloading without restart

After adding or editing an MCP server config, you don't need to restart Hermes:

/reload-mcp

Filtering MCP tools

Some MCP servers expose dozens of tools, which can bloat your context. Hermes lets you allow-list which tools from a server are visible:

mcp:
  github:
    allowed_tools:
      - get_repository
      - list_issues
      - create_pull_request

Two transport modes

• stdio — the MCP server runs as a subprocess. Most common.
• HTTP — the MCP server runs as a long-lived HTTP service. Useful for shared servers across multiple users.

Hermes supports both. Choose based on the server's docs.

Building your own skill

A skill is just a markdown file with structured front matter. No code required.

Step 1 — Decide what the skill does

Pick something specific that you do often. Bad skill: "be helpful with writing." Good skill: "generate a 7-slide Instagram carousel from a topic, following the brand voice in HERMES.md."

Step 2 — Create the folder + file

mkdir -p ~/.hermes/skills/social-media/ig-carousel-generator
cd ~/.hermes/skills/social-media/ig-carousel-generator
touch SKILL.md

Step 3 — Write SKILL.md

---
name: ig-carousel-generator
description: Generate Instagram carousels — 7 slides, one
  idea per slide, brand-matched copy. Trigger: "carousel",
  "ig carousel", "instagram carousel".
metadata:
  tags: instagram, content, social
---

## When to use
Whenever the user asks for Instagram carousel content,
slide concepts, hooks, or layouts.

## Required inputs
1. Topic (one sentence)
2. Angle (authority | contrarian | hidden | tutorial)
3. Brand voice (read from HERMES.md if present)

## Output format
Return a markdown table:
| # | Slide |
|---|-------|
| 1 | Cover hook (≤8 words) |
| 2-6 | Body (one claim each) |
| 7 | Save trigger + soft CTA |

## Style rules
- Cover ≤8 words
- Each body slide ≤25 words
- Bold the keyword that carries the slide
- Final slide always has a save trigger

Step 4 — Reload + test

/reload-skills

The new skill appears in /skills list and is triggerable via /ig-carousel-generator or implicit triggers ("write me an IG carousel about X").

Tips for great skills

• Be specific in the description — Hermes uses it to decide when to load. Include trigger phrases.
• Show, don't tell — include a worked example in the SKILL.md so the model has a template to mimic.
• Constrain output format — exact table headers, exact length limits, exact bullet count. Fewer degrees of freedom = more consistent output.
• Iterate — when a skill underperforms, edit SKILL.md and reload. No build step.

Sharing your skill

Publish to the Skills Hub:

/skills publish ig-carousel-generator

Hermes packages the folder and pushes to agentskills.io. Others can install your skill the same way you install community ones.

config.yaml — top-level keys

Lives at ~/.hermes/config.yaml. Edit, restart the gateway if needed.

.env — secrets & credentials

Lives at ~/.hermes/.env with mode 600. Format is one KEY=VALUE per line.

The full list lives in your installed .env file, fully commented. Open it with open ~/.hermes/.env (macOS) or your favourite editor.

Debugging Hermes

Three tools cover 95% of issues: hermes doctor, the logs at ~/.hermes/logs/, and /debug.

hermes doctor

Runs a battery of checks: Python version, Node version, ripgrep, ffmpeg, Playwright, API keys configured, providers reachable, gateway status, disk space, permissions.

hermes doctor

Each check returns a green tick or a red cross with an explanation of what to do. Run it whenever something feels off. It is the first command to try when an install seems broken.

Logs

All logs live under ~/.hermes/logs/.

/debug — shareable diagnostic bundle

Type /debug in the TUI or messaging. Hermes packages system info, recent logs (anonymised), and config (with secrets redacted) into an upload and returns a shareable URL. Useful when you need to ask the community or the maintainers for help — paste the URL into Discord/GitHub.

Common errors

Mastery patterns

The handful of workflows that separate beginners from operators.

Pattern 1 — Goal loops

Use /goal for any task that takes more than one turn to finish. The judge model decides when it's done, Hermes auto-continues, you don't have to babysit. Budget defaults to 20 turns.

/goal Build a simple Next.js landing page for our launch.
Then deploy it to Cloudflare Pages.

Pattern 2 — Steer mid-run

When the agent is on the right track but slightly off, don't interrupt. Use /steer to inject a note. The agent picks it up after the current tool call without losing momentum.

/steer Focus on the auth module first.
Skip the dashboard until later.

Pattern 3 — Background sessions

Hand off long-running work to a background session so your main session stays free.

/background Crawl example.com, extract every product page,
save the structured data as JSON.

You get notified when it's done. Meanwhile your current session keeps moving.

Pattern 4 — Handoff between platforms

Start a session on your laptop. Need to step out? Hand it to Telegram:

/handoff telegram

The CLI exits cleanly with a /resume hint. Open Telegram — the conversation continues there.

Pattern 5 — Profiles for separate identities

Run two completely separate Hermes installations side by side. Different models, different skills, different memory:

hermes profile create work
hermes profile create personal
hermes profile switch work

Each profile is its own ~/.hermes/<profile>/ directory.

Pattern 6 — Quick commands

Map a short slash command to a shell command or another slash command. Configured in config.yaml:

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  deploy:
    type: exec
    command: scripts/deploy.sh
  inbox:
    type: alias
    target: /gmail unread

Pattern 7 — Always-on VPS

The real Hermes setup is on a $5 VPS, not your laptop. Cron actually fires. Telegram bot is always responsive. Sessions survive your laptop closing. Install via the same one-liner, run hermes gateway start, and forget about it. SSH in only when you need to update.

Cheat sheet

The printable reference. Keep it next to your keyboard.

Setup

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc
hermes setup --portal     # fastest path
hermes                    # launch the TUI

Daily commands

hermes                    # start chatting
hermes gateway start      # turn on messaging bots
hermes gateway status     # check what's running
hermes model              # change provider/model
hermes doctor             # diagnose everything
hermes update             # pull latest version

Top slash commands

/new          # fresh session
/resume       # pick up a past one
/model fav    # switch model via alias
/goal <text>  # persistent goal across turns
/steer <text> # inject mid-run
/background   # spawn parallel session
/handoff tg   # move to Telegram
/skills       # browse + install
/cron         # scheduled tasks
/kanban       # task board
/debug        # shareable bundle
/yolo         # skip all approvals

Power moves

• Install on a $5 VPS, not your laptop
• Wire Telegram first — turns Hermes into a pocket agent
• Use /goal for anything multi-step
• Write SOUL.md early, refine it as you go
• Build one custom skill per recurring task — they compound
• Pin critical skills with /curator pin so they never get archived
• Use hermes model fav aliases so you never type long model strings
• Run hermes doctor first whenever something feels broken

Where things live (memorise this)