Hermes Beginner Tutorial Needs a Rewrite

I originally didn’t want to write a Hermes beginner tutorial. A tool that has been out for so long, writing a “start from zero” guide sounds a bit like chasing old hype. However, I recently reviewed several older tutorials and walked through the v0.13.0 update again, and I came to the conclusion that this piece is necessary.

Tools like Hermes suffer most from outdated tutorials. An outdated tutorial is more troublesome than having no tutorial at all because it is mostly correct. The installation commands might still work, providers can be configured, and the CLI can chat a bit, leading users to easily assume the problem lies with themselves. However, the new version has pushed many features toward production readiness: durable multi-agent Kanban, /goal, checkpoints v2, Gateway automatic session recovery, no_agent cron, Google Chat, providers plugin, Curator for maintaining skill libraries, and even stricter security defaults than earlier versions.

The trouble hides here. Old tutorials often focus on “getting it running,” whereas the new Hermes truly requires “keeping it maintained.” The former involves installation, selecting a model, and sending the first message; the latter also involves managing memory, skills, message entrances, task scheduling, profile boundaries, and automation. If the order is mixed up, it becomes the classic Agent beginner disaster: the tool looks powerful, but the user sits in front of the screen for half a day checking tokens, allowlists, base URLs, and profile statuses.

Especially those articles that start by talking about a “24/7 Agent Legion.” It looks exciting, of course: automatic order acceptance, automatic article writing, automatic publishing, multi-platform scheduling, Feishu middle platform, task boards, long-term memory—all laid out at once, as if you could stuff an entire company into a computer by tomorrow.

I do not recommend doing this on day one. A wrong bot token, a wrong profile switch, or a wrong local model endpoint can consume half a day.

So, this is still a beginner tutorial, but not the “just copy this command” kind. I want to write a dumber but more stable sequence, raising a Hermes from scratch, first making it speak stably, use tools, recover sessions, and know what to remember and what not to. Once this foundation is solid, then connect Gateway, Memory, Skills, Profile, Cron, and Kanban.

First, let one Hermes work stably.

What Exactly Is Hermes?

First, don’t confuse Hermes Agent with the Hermes model. The names are similar, but they are not the same thing.

In my view, Hermes is more like an Agent runtime. The model is just the brain; Hermes manages the troublesome things outside the brain: tools, sessions, memory, Skills, automated tasks, chat entrances, multi-agent profiles, and task boards.

Ordinary chat tools are like temporarily summoned assistants who scatter after the question is answered. Hermes is more like setting up a desk for this assistant, with a notebook, SOPs, message entrances, and a task board nearby. For a quick concept explanation, such heavy machinery isn’t needed; compiling daily reports, tracking materials, maintaining projects, saving preferences, and executing low-risk tasks on a schedule are where it shines.

Three Things Not to Do on Day One

Beginners are most easily led astray by “advanced playstyles.” I am no exception; seeing multi-platform Gateways, multiple profiles, and Kanban scheduling makes one’s hands itch. But opening all these things on the first day will cause the debugging surface area to expand rapidly.

Telegram, Discord, Slack, WhatsApp, and Feishu can all be connected. The problem is that if any bot token, allowlist, home channel, or platform permission is not configured correctly, Hermes will look broken. Multi-agent is the same; profiles are powerful, but each profile has its own configuration, keys, memory, sessions, skills, cron jobs, and gateway status. Creating a commander, coder, reviewer, and researcher all at once will double the debugging surface area.

Hold off on local models for now. Local models are fun, but when starting for the first time, base URL, model name, OpenAI-compatible interface, context length, and tool call stability will all rush at you. First run through a stable cloud provider to establish a benchmark, then connect Ollama or vLLM, and you will avoid many detours.

I would follow this order: Install Hermes → Choose model provider → Run CLI/TUI session → Confirm sessions can recover → Configure SOUL/Memory → Use Skills → Connect Gateway → Build Profile → Use Cron/Kanban/Docker

First, Get the Version Running

Installation itself is not complicated. The official script is just this one line:

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

This line works for macOS, Linux, and WSL2.

If you are using Windows, you no longer need to go through WSL2 first. The official Windows Native Beta has been released and can be installed directly in PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 -UseB | iex"

Let me clarify this. Native Windows support is real, not my imagination; but it is still in beta. Core capabilities like CLI, TUI, Gateway, Profile, and Skills can follow the native Windows path, but the embedded terminal in the Dashboard is still more biased toward WSL2 scenarios. If you just want to run Hermes on Windows, you can go with the native installation; if you want to do heavy development, long-term automation, and complex local toolchains, WSL2 is still the more stable option.

After installation, reload the shell. In Windows PowerShell, simply open a new window before running subsequent commands.

source ~/.bashrc # or source ~/.zshrc

I will immediately check the version:

hermes --version

The latest version output looks something like this:

Hermes Agent v0.13.0 (2026.5.7)
Up to date

Do not skip this step. Hermes changes frequently; many “tutorial failures” are not because the author wrote it wrong, but often just because commands have sprouted new branches.

If you plan to use it seriously, do not delay the doctor check either:

hermes doctor

It is not mysterious; it just scans the environment, configuration, and dependencies. It is better than staring at error messages and guessing for half a day.

I will also casually run:

hermes --help

Running it is not for memorizing commands. Taking a look at the entrances first makes you feel much more stable. model, gateway, cron, kanban, skills, curator, memory, profile, dashboard, and logs are all in this one screen. The current focus of Hermes is actually written in this list of commands.

Second, Connect the Model First

Hermes is not a model; it must connect to a provider.

The most stable entrance is:

hermes model

There are many officially supported providers: Nous Portal, OpenRouter, OpenAI Codex, Anthropic, Kimi, Qwen, DeepSeek, Hugging Face, AWS Bedrock, GitHub Copilot, Vercel AI Gateway, custom OpenAI-compatible endpoints, etc.

For the first use, do not pursue the most flashy option. Getting it to run is the most important thing.

I would choose in this order:

1. Have a stable API Key → Use it first.
2. Don’t know what to choose → OpenRouter or Nous Portal.
3. Want to use domestic models → Kimi / Qwen for simple tasks first.
4. Want to use local models → Wait until the CLI runs smoothly, then connect Ollama / vLLM.

There is also a hard condition that is often overlooked: Hermes requires the model to have at least a 64K context. Agents need to carry tools, history, memory, and task status; small context models easily lose memory halfway through.

After configuring the model, do not connect Telegram yet. First confirm in the terminal that it can answer.

hermes --tui

Or the classic CLI:

hermes

The first test should not ask philosophy, nor should it write a large project. Ask a task that can verify tools:

Please check the current directory, tell me the 5 files here that look most like the main project entry point, and explain your basis for judgment.

The success criteria are simple:

• It knows the current provider and model.
• It replies normally.
• It can call file or terminal tools when needed.
• When you ask a follow-up question in the second round, it does not break.

If this step passes, Hermes can be considered to have vital signs.

Third, Confirm Sessions Can Recover

One of the biggest differences between an Agent workspace and ordinary chat is the ability to continue working.

After running a simple session, exit, and try again:

hermes --continue

Or:

hermes -c

Being able to return to the previous context indicates that session basics are normal. Long-term tasks, multi-agents, Gateway, and Cron will all use this.

If it cannot recover, check first:

hermes sessions list

Many people think memory is broken, but it’s often just a switched profile or a session that wasn’t saved.

Fourth, Understand Hermes’ Several Configuration Files

Hermes configuration is not difficult; the difficulty is not putting things in the wrong place.

• ~/.hermes/.env: Place keys. API Keys, bot tokens, platform tokens go here. Do not share with others, do not paste into public repositories.
• ~/.hermes/config.yaml: Place ordinary configurations. For example, default model, terminal backend, gateway, tool switches.
• ~/.hermes/SOUL.md: Place stable persona and hard rules. For example, verify before answering, warn for dangerous commands, do not fabricate APIs, explain how to verify after completing tasks.
• ~/.hermes/memories/MEMORY.md: Place the Agent’s work notes. For example, this machine’s environment, project habits, pitfalls encountered.
• ~/.hermes/memories/USER.md: Place user preferences. For example, default Chinese, conclusion first, less long-winded nonsense.
• AGENTS.md in the project root: Place project-level rules. For example, how to test this project, which directories cannot be touched, what commands to run before release.

The mistake most easily made here is stuffing everything into MEMORY.md. I used to do this too, and it got messy quickly. Fixed rules should go in SOUL.md, project standards in AGENTS.md, changing environmental facts and work notes in MEMORY.md, and user preferences in USER.md.

A beginner’s first version of SOUL.md does not need to be like a company policy; a few lines are enough:

# Hermes Behavior Rules
For uncertain commands, paths, and configurations, check before answering.
For tasks with more than three steps, list the plan first.
Explain risks for high-danger operations; do not execute directly.
Tell me how to verify after completing tasks.
Do not write temporary guesses into long-term memory.

Do not write a two-thousand-word persona at the start. Writing it too full means you won’t know which rule is working later, and Hermes probably won’t either.

Fifth, Memory and Skill Are Not the Same Thing

What is interesting about Hermes is not that it “remembers me,” but that it can separate memory from process.

Memory records facts and preferences. For example:

When compiling AI tool updates in the future, keep English product names, original links, and Markdown format.

This is suitable for Memory.

Skill records processes and SOPs. For example:

Every time generating an AI tool daily report, first scrape AI hot, then look at X popular tweets, then categorize by agent/coding/video/image/infra, and finally give 5 writable topics.

This is suitable to be sedimented into a Skill.

I distinguish them like this: Memory = What it should know Skill = How to do a certain type of task

When training Hermes, shouting “remember me” every day is of limited use. Once a task runs smoothly, directly have it sediment into a Skill for more stable results:

We will use this process repeatedly in the future. Please save it as a Skill, including trigger conditions, execution steps, precautions, and verification methods.

After writing, do not trust it blindly; check it:

hermes skills list

External skills can also be searched:

hermes skills search github
hermes skills inspect
hermes skills install

The latest version also has Curator. I quite like this feature; it manages agent-created skills, merges duplicates, archives obsolete ones, and clears out low-quality ones.

hermes curator status
hermes curator run

It is not there to randomly delete skills. According to the current help documentation, bundled and hub-installed skills are not automatically handled by it; archives can also be restored. Treat it as skill library housekeeping, not as a skill library executioner.

Sixth, Connect Gateway, Let Hermes Appear in Chat Software

After the CLI runs smoothly, then connect the Gateway.

hermes gateway setup
hermes gateway run

For long-term operation, you can use:

hermes gateway install
hermes gateway start
hermes gateway status

If just testing locally, gateway run is more intuitive. It runs in the foreground, so errors are visible directly. Wait until everything is stable, then install it as a background service.

When connecting platforms, choose one first. For personal use, Telegram or Discord is usually fastest. For team collaboration, Feishu is more convenient. For specific platforms, refer to the current version’s hermes gateway setup menu; do not force old tutorials to fit.

Gateway success is not judged by whether the service started, but by whether you can send a message to Hermes in the chat software and receive a reply.

The first message can be simple:

Please reply with one sentence stating that you have accessed Hermes through the current chat platform.

Send a second message:

Please remember, in the future, when I ask you to compile materials from this chat entrance, default output Markdown, and keep original links.

On the second day, use different wording to have it do a similar task and see if it沿用 (follows) the preference. Testing to this step counts as testing the combined ability of Gateway + Memory.

Seventh, Profile Is the Correct Starting Point for Multi-Agent

Many people talk about multi-agent, but they actually mean multiple profiles.

A Profile is an independent Hermes home. Each profile has its own config.yaml, .env, SOUL.md, memories, sessions, skills, cron jobs, and state database.

Create a coding assistant:

hermes profile create coder --clone
coder setup
coder chat

Create a review assistant:

hermes profile create reviewer --clone
reviewer setup
reviewer chat

--clone means copying the current configuration, keys, and SOUL, but giving the new profile a new set of sessions and memory. It is suitable for creating agents that are similar but have different responsibilities.

If you want a complete copy, including memory, sessions, skills, and cron, you can use:

hermes profile create backup --clone-all

Here is a pitfall that must be mentioned: Profile is not a sandbox.

Profile is state isolation. It isolates configuration, memory, sessions, and skills, but it does not isolate file permissions. Under the default local terminal backend, it still accesses the file system as the current user.

If you only want it to work in a certain project directory, set terminal.cwd. If you want to restrict the command execution environment, you must use backends like Docker, SSH, Modal, Singularity.

Remember this sentence: Profile manages identity and state; Sandbox manages permissions and boundaries.

Do not mix the two.

Eighth, What Problem Does Docker Actually Solve?

Docker and Hermes have two relationships.

The first is running the Hermes entity inside Docker. This is suitable for deploying long-term online services and reducing pollution of the host environment.

The second is Hermes running on the host, but entering a Docker sandbox when executing terminal commands. This is suitable for scenarios where you do not want the Agent to directly touch the host.

These two are not the same thing.

Running the Hermes entity in Docker, the minimal form is roughly:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Background gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

The core is this mount: ~/.hermes:/opt/data

Because /opt/data is the Hermes state directory inside the container. .env, config, sessions, memories, skills, cron, logs are all here. Without mounting, many things are gone after container rebuild.

If you just want Hermes command execution to be safer, you can first use:

hermes config set terminal.backend docker

At this time, the Hermes entity is still on the host, and only the terminal tool enters Docker.

Ninth, Kanban Is the Most Worth-Watching New Capability in the Latest Version

If only doing personal chat, Kanban is not something to open on the first day.

But to have multiple Hermes profiles collaborate like a small team, Kanban is crucial.

In the latest version, you can view directly:

hermes kanban --help

Its description is clear: this is a durable SQLite-backed task board. Tasks can be atomically claimed, dependencies can be set, and named profiles can execute in isolated workspaces.

The latest version continues to push this forward, adding heartbeat, reclaim, zombie detection, retry budget, incomplete exit auto-block, and other capabilities. Translated into human language: previously, multi-agents were like “sent out and left to fate,” now it is more like having a task board, heartbeats, failure recovery, and handover records.

To get started, you only need to know these commands:

hermes kanban init
hermes kanban boards list
hermes kanban create --help
hermes kanban list
hermes kanban show
hermes kanban dispatch --help

Do not let it automatically take over a large project on the first day. A more suitable exercise is: Create a small task board, AI Daily Report Production. Task A: Collect 10 AI hot items. Task B: Filter out 5 writable topics. Task C: Write titles and reader pain points for each topic.

Let the researcher profile do A, and let the editor profile do B and C. Such tasks have low failure costs, clear structure, and are suitable for testing Kanban.

Tenth, Cron Is Suitable for Fixed Tasks, Not for Making Wishes

Hermes has cron:

hermes cron list
hermes cron add
hermes cron status
hermes cron run

The latest version also added no_agent cron; certain watchdog-type tasks run scripts only and do not need to start the Agent every time.

My first batch of tasks for cron is usually very conservative. Produce an AI tool briefing in the morning, back up a directory at night, audit Skills once a week, or check if a webpage has updated every day. These jobs are easy to handle if something goes wrong.

Automatic article publishing, automatic file deletion, automatic account operation—I do not recommend handing these over to it on the first day. Automation is not better the more aggressive it is; it must be reviewable, rollbackable, and explainable to run long-term.

Debugging Order

When Hermes has problems, the worst thing is to blindly modify .env and config.yaml based on feelings. I generally run this string first:

hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
hermes gateway status
hermes logs errors

• hermes: command not found: Mostly means the shell has not been reloaded. First source ~/.bashrc or source ~/.zshrc.
• Model does not reply: Check provider, API Key, model name, base URL first.
• Local model is strange: Focus on whether the endpoint is OpenAI-compatible, whether the context is sufficient, and whether the model name matches what is actually loaded.
• Gateway started but no messages received: Do not rush to reinstall. Check token, allowlist, pairing, home channel, and platform permissions item by item.
• Memory not taking effect: First confirm if it is the same profile, then check if the session recovered, and if MEMORY.md / USER.md was written.
• Profile accessing external files is not strange; profile manages state, sandbox manages boundaries.
• Configuration lost after Docker restart: Most likely ~/.hermes was not mounted to /opt/data.
• Skills are messy: First look at hermes skills list and hermes skills audit, do not manually delete a bunch right away.

A Practice Suitable for the First Week: AI Daily Report Assistant

I think the first week is best practiced with an AI Daily Report. It is real enough, yet not dangerous; if it fails, at most the briefing looks bad, it won’t delete your project.

Day One: Throw this task directly in the CLI:

Please help me generate today’s AI tool update briefing. Requirements:

1. Keep product name, original link, and update time for each item.
2. Categorize by agent / coding / video / image / infra.
3. Output Markdown.
4. Write at the end which preferences are worth keeping next time.

After it finishes, do not just look at the content; correct the format. For example:

In the future, do not write vague evaluations for this type of briefing. Keep only facts, links, and one sentence “reason to watch” for each item. Please write this preference into your memory.

Day Two: Change the requirement:

Continue yesterday’s AI tool update briefing. But this time, keep only the 5 items most worth writing as public account articles. For each item, provide: title direction, reader pain points, practical deliverables.

Do this continuously for three days, and it can be sedimented into a Skill:

We have done the AI tool update briefing three times in a row. Please save the stable process as a Skill named ai-daily-brief. Requirements include trigger conditions, information sources, filtering rules, output format, and verification methods.

This is much more practical than shouting “Help me build an AI empire” on the first day. Small tasks are safe, low-cost, and reviewable. Hermes can also gradually remember preferences and sediment processes in this process. Afterward, connecting chat software, scheduled tasks, Profiles, and Kanban will give you confidence.

Wrap Up

I value Hermes mainly because of “continuity.” Many AI tools are not stupid, but they break too easily. Today you just taught it a format, tomorrow it forgets it in a new window; today you fixed a pitfall, the day after tomorrow it circles back and makes the same mistake again.

Hermes putting memory, skills, sessions, gateway, profiles, and kanban together is precisely aimed at this fragmentation.

But it is not a maintenance-free machine. Models need to be selected, keys managed, tools configured, logs checked, permissions audited, Skills cleaned, and task boundaries designed. It will grow, but what it grows into largely depends on how humans feed tasks, give feedback, and allow it to save certain processes.

My advice is still very earthy. Run through one session first, then cultivate one process, then organize one team.

Three things are enough for Day One:

hermes model
hermes --tui
hermes doctor

Able to speak, able to use tools, able to recover, able to debug.

With this foundation laid, Hermes qualifies to become a long-term AI workspace.