Hermes Agent guide: what it is, when to use it, and how to get started

Hermes Agent is an open-source AI assistant from Nous Research that can work with files, run tools, and carry useful information from one session to the next. You choose the model it talks to and the environment it can act in. Hermes supplies the machinery around that model: conversations, tool execution, memory, reusable skills, and ways to reach the assistant from a terminal, desktop app, or messaging service.

The interesting part comes after the first task. A chat can explain how to review a deployment. A tool-using agent can read the deployment files and prepare the review. Hermes can also preserve the procedure so that next week's review starts with the method you already worked out. That is a useful ambition. It is also where an old assumption can quietly acquire a permanent address.

This guide explains how those pieces fit, where Hermes came from, what it is good for, and what running it involves. Then we'll set up a small Linux lab, produce a report with an answer you can check, and turn the reviewed method into a skill. The example is deliberately modest. An assistant that cannot distinguish fresh evidence from last week's answer is not ready for a larger job.

The walkthrough targets Hermes v0.22.0, checked against official documentation and tagged source on October 14, 2026. Hermes was not installed or run for this article. The worked examples are constructed teaching material, not recorded agent results.

What you actually install

Hermes is an application around a language model, rather than a language model itself. This matters because installing Hermes does not download a universal brain, provide unlimited inference, or automatically keep your data on your computer. The project is MIT-licensed; the services and hardware you connect to it have their own terms and costs.

Suppose you ask it to compare a runbook with a configuration file. Hermes sends the request, relevant context, and descriptions of available tools to your selected model. The model can request a file read. Hermes runs the operation, returns the result, and calls the model again. The next step might be another read, a calculation, or the finished comparison. This repeated exchange is the agent loop. Hermes overview.

Four separate choices determine what that loop can do:

Inference is the model producing a response from its inputs. OpenRouter is a route to models supplied by different providers. Neither is a replacement for Hermes's file handling, skills, or session management. Conversely, Hermes does not become a better model simply because it has more tools. A weak choice of action can now be executed very efficiently. Hermes provider integrations.

There is another naming trap: Nous also develops the Hermes model family. Its Hermes 3 and Hermes 4 releases predate this agent. Hermes Agent can use models from other developers; a Hermes-branded model is not a requirement. The shared name identifies the Nous ecosystem, not one indivisible product. Nous release history.

From a Nous project to a broader assistant

Nous Research lists Hermes Agent's launch as February 25, 2026. Its March 12 v0.2.0 release describes a small internal project that had expanded through community contributions. By then, the project included a messaging gateway, MCP integrations, reusable skills, and editor connectivity. The persistence and tool-use ideas were part of its early shape, rather than features bolted onto a coding-only product much later. Nous launch listing and March 12 release notes.

The next important change for someone choosing it today was the desktop application. The v0.16.0 release, dated June 5, introduced an Electron-based app for macOS, Windows, and Linux, including connections to a remote Hermes gateway. The distinction is useful: the computer showing the chat window does not always have to be the computer doing the work. GitHub published that release shortly after midnight UTC on June 6. Desktop release notes.

The current v0.22.0 release adds guided desktop onboarding, hosted-app connectors, and a managed local-model route built on llama.cpp, among other changes. Its notes are dated October 13; GitHub records publication on October 14 UTC. Hermes is now broader than the terminal agent shown in many early tutorials. Nous Research remains the project behind it, with development in the open and contributions from the community. v0.22.0 release notes.

That pace explains why this guide names a specific version. A six-month-old screenshot can be perfectly genuine and still describe a setup menu you no longer have.

What “learning” means here

Hermes can retain several kinds of information. They solve different problems, and confusing them is an easy way to get a convincing answer to yesterday's question.

A session is the saved conversation: requests, tool results, and replies that let you continue earlier work. Memory keeps selected facts and preferences available across sessions. A skill stores a procedure, usually in a SKILL.md file with any supporting material, that the agent can load when the task calls for it. Memory might say that a project uses UTC. A skill explains how to calculate freshness. A session contains the report produced on Tuesday. Memory system and skills system.

These mechanisms do not retrain the underlying model's weights when you finish a conversation. They change the information and instructions available to subsequent model calls. That is still useful. You can inspect and revise a saved method instead of hoping the model independently rediscovers it each time.

It also means “self-improving” needs a little unpacking. The ability to write a skill is a product capability; whether the new skill improves your work is something to verify. If Hermes saves an incorrect assumption, persistence can make the mistake more consistent. Our practical test later changes the input data and checks whether the saved method produces a different answer.

Where Hermes can be useful

Hermes makes the most sense when a job crosses several steps or sources and some part of the method is worth keeping. The following are possible uses of its documented capabilities, not claims of results achieved in this article.

Research and documentation are a natural fit. With the relevant web and file tools enabled, an assistant can collect official release notes, compare them with a local inventory, and draft an upgrade brief. The useful output is more than a summary: it connects a documented change to the version or setting you actually run. Keep the source links and unresolved questions in the brief, so a reviewer can follow the comparison. Hermes provides web, file, and terminal toolsets, but each must be available in the configuration you use. Tools and toolsets.

Browser automation and media tools widen the kinds of input Hermes can work with. A browser task may need to navigate a page rather than merely retrieve its text; an image-analysis task needs a capable model and the relevant tool. These are optional capabilities with their own setup and sometimes service costs, not abilities that every minimal installation automatically has. Available tool categories.

Coding and repository work fit the same loop. Hermes can inspect files, edit code, and run commands; project instructions can tell it where tests live and which conventions matter. For an operator, that could mean drafting a parser for an awkward export or tracing how a configuration option reaches an application. A proposed patch is an artifact to review and test, rather than evidence that the system has been fixed. The second example below stays at the earlier, read-and-compare stage. CLI capabilities and project context files.

Recurring assistant work is where persistence becomes more noticeable. A weekly release digest, a recurring inventory comparison, or a draft operational handover can reuse the same instructions while reading new inputs. Hermes's scheduler can launch fresh agent sessions and deliver their results. Its messaging gateway can make the assistant reachable through services such as Telegram, Discord, and Slack. A schedule needs the gateway running; a remembered request alone is not a running job. Scheduled tasks and messaging gateway.

A less technical example is a recurring planning meeting. Suppose you have this week's notes, last week's decisions, and a preferred agenda format in local files. You could ask Hermes to draft the next agenda, cite which note supports each unfinished item, and leave completed work out. After reviewing it, save the agenda-building procedure as a skill. Next week, supply new notes. The time saved comes from retaining the structure and comparison method, while dates, owners, and unfinished work come from the new material. You would still review the draft before sending it to participants; none of this requires granting access to your calendar or mailbox. This is an illustrative workflow using the same file and skill capabilities as the lab, not a claimed execution.

Connected application work extends that reach. MCP, the Model Context Protocol, lets Hermes use tools exposed by external servers. Current hosted connectors offer another route into supported applications. This can remove copy-and-paste work between a ticket, a document, and a local report, but it also changes which data and actions are available to the agent. Connecting an app is an access decision, not just an item to tick during setup. MCP integration and current connector release.

When another approach is simpler

The question is not whether Hermes has enough features. It is whether those features remove work you actually have.

If you want an explanation of a log excerpt and will do the follow-up yourself, a chat interface may be sufficient. If the job is a fixed calculation over a stable schema, a script is easier to make deterministic and test. The freshness arithmetic later in this guide is deliberately simple enough to do without an agent. Hermes adds value around interpreting the task, preparing the report, and carrying the reviewed procedure forward; it does not improve subtraction.

For a terminal-first coding workflow, Pi is a relevant comparison. Its own documentation describes a minimal coding harness with extensions, skills, and prompt templates. It gives you a smaller core to adapt. Hermes packages more of the persistent-assistant experience, including memory, messaging, and scheduling. Choose based on whether you want to assemble a coding environment or operate a broader assistant, rather than assuming that a longer feature list settles the decision. Pi's project documentation.

OpenClaw is a closer comparison for an assistant you reach through multiple chat channels. Its documentation emphasizes a self-hosted gateway, sessions, tools, and a plugin ecosystem. There is substantial overlap. Compare the specific integrations you need, how you will maintain the deployment, and how each handles your actual task. This guide does not establish a reliability or performance winner between them. OpenClaw overview.

Hermes is also a poor starting point for unattended production remediation when you have not yet checked its outputs, permissions, and recovery behavior. A fluent explanation of a restart is not evidence that a restart is warranted. Start with checkable reports and validate any saved skill on changed data before giving it production access.

The costs behind a local install

There are three separate bills to think about: the machine running Hermes, model inference, and any paid tools or services you enable. The open-source license does not make those other resources free.

With a hosted model, an apparently small request can lead to several model calls. Each call may include instructions, earlier conversation, and fresh tool results. Reading a large log into the conversation can therefore cost more than the final three-paragraph answer suggests. Hermes exposes token and estimated-cost information through /usage; the provider's billing records remain the place to reconcile actual charges. CLI usage reporting.

For scale, the OpenRouter listing checked for this guide prices Claude Sonnet 4.6 at $3 per million input tokens and $15 per million output tokens. An illustrative total of 20,000 uncached input tokens and 2,000 output tokens would therefore be $0.09 in model-token charges. That is arithmetic, not a price promise for completing a task: repeated calls, caching, other tools, and provider pricing conditions change the bill. Set a small key limit for the lab and check current rates before using it. Model pricing and API-key limits.

A local model replaces hosted inference charges with hardware, memory, electricity, and administration requirements. Hermes supports local and self-hosted endpoints, but the model still needs usable tool calling and enough context for the task. Selecting a local endpoint also does not make web tools, hosted connectors, or auxiliary services local. Review the entire configured data path before treating a deployment as private or offline. Local-provider configuration.

Choose a first setup you can understand

If you want the graphical application, use the official desktop download and its platform-specific installation guidance. You do not need to learn the CLI to qualify as a Hermes user. The desktop is a valid front door to the same product.

For this walkthrough, use a disposable Ubuntu 24.04 VM, a dedicated non-root account, and one hosted model through OpenRouter. This gives the commands and generated files an obvious home, without first adding your everyday workstation, messaging accounts, or production credentials to the experiment. It is a teaching setup, not a claim that every deployment needs a VM or OpenRouter.

Before installing, have these ready:

• A normal user account in the VM. An administrator can install system packages, but run Hermes as the normal user.
• Git, curl, tar, and SHA-256 utilities. Source builds may also need a compiler and development libraries. On minimal Ubuntu images, the managed Node runtime needs libatomic1.
• Internet access for installation and the model API. Do not attach your ordinary home directory, forward an SSH agent, or copy production credentials into the VM. Keep the lab off production networks.
• An OpenRouter account and API key with a small spending limit. Check the selected model's price and data-handling terms. Choose a tool-capable model with at least 64,000 tokens of context, the minimum stated in the current Hermes quickstart.

The model provider receives the content included in model requests, so this exercise uses invented data. Installation prerequisites, provider setup and context requirement, and OpenRouter key limits.

The source installer manages its Python and other runtime tools. Current first-party installations use Python 3.14; an older tutorial telling you to prepare a Python 3.11 environment is not the setup followed here.

Install the reviewed release

Download the tagged installer so you can read it before executing it. The script will download software and prepare Hermes in this account. Review it with your editor, or use your organization's approved software-installation process.

curl -fsSLo hermes-install.sh \
  https://raw.githubusercontent.com/NousResearch/hermes-agent/v0.22.0/scripts/install.sh

After reviewing it, run:

bash hermes-install.sh \
  --commit e06df9c2eae6901f4c88f464e0ae6e753c0428b8 \
  --non-interactive --skip-browser --skip-computer-use

export PATH="$HOME/.local/bin:$PATH"
hermes --version

The commit selects the v0.22.0 source. Merely downloading an installer from a release tag would not pin the code it installs. The other flags skip interactive setup and optional browser/computer-use downloads, so the next step is a deliberate configuration pass. This is not an offline install: dependencies and managed tools are still downloaded. Tagged installer and v0.22.0 release.

Connect a model and choose the local tool backend

hermes setup

On this fresh installation, choose Blank Slate, select OpenRouter, and enter the key in the setup flow. For this walkthrough, select anthropic/claude-sonnet-4.6. OpenRouter currently lists tool support and a one-million-token context window for it. This is a concrete starting configuration, not a claim that it is the best model for every job. Model listing. When asked about the terminal backend, choose local. Here, “local” means commands run in the VM under the account running Hermes.

Finish with Start with everything disabled, the minimal-finish choice, rather than walking through all the optional configurations. Despite that label, v0.22.0 retains a small baseline, including file and terminal tools, vision, and skills support. Built-in memory is disabled. Bundled skill files may already exist from installation; inspect them with hermes skills list before the later skill exercise. The first chat command below narrows the offered toolsets further. This detail comes from the tagged setup implementation, which is more precise than the current quickstart's summary of Blank Slate.

Set the command-approval policy and check the installation:

hermes config set approvals.mode manual
hermes config get terminal.backend
hermes doctor

The backend should be local. Investigate provider or installation errors reported by the diagnostic before adding integrations. Manual approval means Hermes asks about commands that match its dangerous-command checks; it does not mean every tool call requires permission. Approval modes.

First task: a successful job with stale data

A green job status answers whether a run finished successfully. It does not necessarily answer whether the run loaded current data. This synthetic example gives Hermes both the run history and a freshness rule, then asks for a report that keeps those questions separate.

Create a new directory in the VM:

mkdir -p ~/hermes-freshness-lab
cd ~/hermes-freshness-lab

Save the following as pipeline-runs.csv. All timestamps are UTC. Each row describes one completed run; max_source_event_utc is the newest source-event timestamp present in that run's loaded data.

run_id,finished_utc,max_source_event_utc,status,rows_loaded
run-101,2026-10-14T09:00:00Z,2026-10-14T08:57:00Z,success,1200
run-102,2026-10-14T09:15:00Z,2026-10-14T08:57:00Z,success,1180
run-103,2026-10-14T09:30:00Z,2026-10-14T08:57:00Z,success,1165

Save the accompanying rule as freshness-policy.md:

This is synthetic teaching data, not a live service.
For each completed run, freshness age is:
finished_utc minus max_source_event_utc.
The target is an age of 15 minutes or less at completion.
A successful job status does not establish that the target was met.
Report observed values separately from possible explanations.
The export contains no source-system or extraction-cursor evidence.
Do not infer a root cause from this export alone.

Start the interactive session from that directory:

hermes chat --toolsets file,terminal

These toolsets allow file operations and terminal commands; they do not make the folder read-only or confine access to it. CLI toolset selection.

Give Hermes this prompt:

Read pipeline-runs.csv and freshness-policy.md in this directory.
Calculate freshness age in minutes for each run.
Identify which runs meet the target and cite the CSV row or run ID.
Explain what the successful status and row counts do and do not show.
Separate observations from hypotheses and identify the next evidence
needed to distinguish the hypotheses.
Write a concise report to freshness-review.md.
Use only these local inputs; do not contact services or change them.

This request lets Hermes choose how to inspect and calculate, while giving you a specific artifact to check. Watch the visible tool calls. If it starts doing unrelated work, interrupt the session and narrow the request rather than treating a long sequence of activity as progress.

Check the report against the fixture

The calculations should be 3, 18, and 33 minutes. Only run-101 meets the target. The other two runs report successful execution and positive row counts, yet their newest source-event timestamp has not advanced.

A useful answer should preserve that distinction. It can suggest inspecting the extraction cursor and checking whether newer source events existed. The CSV cannot tell you whether the source was quiet, extraction was stuck, timestamps were wrong, or another condition caused the repeated watermark. Positive row counts do not settle those questions either.

These are expected findings from the supplied inputs, not sample output attributed to Hermes. Compare the generated file with the CSV yourself. A report that gets the arithmetic right but declares a broken extractor has gone beyond its evidence.

Turn the checked report into a reusable skill

Once the report is correct, the part worth reusing is the method: read the policy, calculate the ages, compare them with the target, and keep missing evidence visible. The October 14 observations belong to this example.

Exit the chat, enable review of skill changes, and resume with the skills toolset available:

hermes config set skills.write_approval true
hermes --continue --toolsets file,terminal,skills

In that session, ask Hermes to capture the reviewed workflow:

/learn Create a skill named pipeline-freshness-review from this workflow.
On every use, read the newly supplied CSV and policy, verify timestamp
units and timezone, and recompute every age. Keep observations separate
from hypotheses. Require new evidence before diagnosing the source or
extractor. Do not save the example's timestamps or findings as current
service facts. Do not add service access or remediation steps.

/learn gives the agent a skill-authoring request; it is not proof that a file was saved. With skill write approval enabled, inspect the staged change:

/skills pending
/skills diff <id>

Replace <id> with the identifier shown by the pending list. Read the complete instructions and any attached scripts. If they capture the intended method, apply that specific change:

/skills approve <id>

If the proposal embeds the sample findings as permanent facts, adds unrelated commands, or otherwise changes the procedure, reject it with /skills reject <id> and explain the correction. These controls cover writes through the skill-management tool; they do not replace the VM's operating-system permissions. Skill learning and write review.

Copy pipeline-runs.csv to pipeline-runs-updated.csv and change only run-103's max_source_event_utc to 2026-10-14T09:27:00Z. Leave the other rows unchanged. Exit the resumed conversation and start a fresh session:

hermes chat --toolsets file,terminal,skills

Invoke the saved skill with the new input:

/pipeline-freshness-review Review pipeline-runs-updated.csv against
freshness-policy.md. Write freshness-review-updated.md.

The final run should now have an age of three minutes and meet the target; run-102 should still fail at 18 minutes. This small counterexample checks whether the saved instructions cause a fresh calculation rather than a repetition of the old answer. It is a proposed verification exercise, not a benchmark result.

Built-in memory can remain off for this workflow. If you later want Hermes to retain stable project conventions, enable Memory for the CLI in hermes tools, set memory.memory_enabled to true, and start a new session. Blank Slate disables both tool access and the underlying memory setting, so changing only one is insufficient. Keep rapidly changing service state in the current inputs. Memory configuration.

Make Hermes understand the project, not just the prompt

A good recurring workflow needs a little context, but it does not need a small novel pasted into every message. Hermes has different places for different kinds of guidance.

Use a project AGENTS.md for conventions that belong with the repository: where the inputs live, how to run tests, what generated files mean, and which assumptions need checking. Hermes discovers project context files from its working environment; higher-priority context types can take precedence, so inspect existing files before adding another. For a clean copy of the lab, a short AGENTS.md could say:

# Report-review lab

Inputs are synthetic CSV files and Markdown policies in this directory.
Use UTC and state the timestamp used for every age calculation.
Write reports to new files; preserve the supplied inputs.
Every report must separate observed values, interpretations, and missing evidence.

That is project guidance, not a permission system. Its purpose is to stop you repeating stable context, while leaving the actual request free to change. The file belongs under version control if it is shared project guidance. Review context files supplied by unfamiliar repositories before asking an agent to work in them. Context-file discovery and precedence.

Use skills for procedures that should travel between tasks. Use memory for durable facts or preferences that are useful across sessions. Use SOUL.md for the assistant's tone and behavior. Hermes loads that identity file from its home directory, normally ~/.hermes/SOUL.md, rather than accepting a project checkout's SOUL.md as its identity. “Be concise and show calculations” is reasonable guidance; “be absolutely certain” cannot supply missing evidence. Personality and SOUL.md.

When a workflow needs a capability Hermes does not have, decide whether the missing piece is instructions or access. A skill can teach it how to use an existing tool. An MCP server or plugin can add tools, with the permissions and software dependencies that entails. Adding an integration to solve an instruction problem creates a new thing to maintain without fixing the original misunderstanding. MCP integration.

For genuinely separate assistants, profiles give each one its own Hermes home: configuration, memory, sessions, skills, and other state. That helps keep a personal assistant's preferences out of a work assistant's context. It is organizational separation, not a replacement for OS isolation. Subagents solve a different problem: they let a parent delegate part of the current work to a fresh conversation. They may share an execution environment, so parallel work still needs clear file ownership and a sensible model budget. Profiles, subagent delegation, and shared execution configuration.

A second task: compare configuration with a runbook

Here is a different use of the same file-reading setup. Create a separate lab folder and save these two small files. They describe an invented service, not a real application's configuration format.

service-config.yaml:

service: invoice-worker
request_timeout_seconds: 30
max_attempts: 3

runbook.md:

# Invoice worker
Requests time out after 20 seconds.
The worker makes at most 5 attempts per request.

Start hermes chat --toolsets file,terminal in that folder and ask:

Compare service-config.yaml with runbook.md.
Write drift-review.md with each disagreement, quoting the relevant
configuration key and runbook sentence. Do not edit either input.
Do not assume the configuration is deployed or that either file is
correct. End with the evidence needed to resolve the disagreement.

The expected findings are two disagreements: 30 versus 20 seconds, and 3 versus 5 attempts. Neither file proves which values the live service uses. A useful next step would be checking the deployed configuration and the application's interpretation of those settings. A model that confidently “fixes” the runbook by copying the YAML has skipped that step.

This is a useful pattern for larger repository work: ask for a comparison with traceable references first, then decide whether a change is warranted. The skill worth saving would describe that comparison process, not decree that configuration files always outrank documentation.

What changes when real systems are involved

The lab keeps production-service credentials and untrusted integrations out of the process for a reason: Hermes can execute work with the permissions of the account running it. A prompt that says “only use these files” guides the model; it does not enforce filesystem or network limits.

The project's security policy makes a distinction worth understanding before you select a backend. A Docker terminal backend confines terminal and file operations to that backend. Other paths, including code execution, MCP subprocesses, plugins, and hooks, can still run from the agent process. To contain the complete process tree, put the whole agent inside the chosen isolation environment. A container around one tool is not automatically a container around everything Hermes does.

There are also two different ways for an agent to make a bad decision. It can misunderstand legitimate evidence, or it can encounter malicious instructions inside a page, file, message, or tool result. The latter is prompt injection: content supplied as data tries to redirect the assistant's behavior. Hermes has protective checks, but its security documentation does not treat model obedience as the final access control. Restrict what the account can read, which services it can contact, and what credentials it possesses. Security model.

For real operational reports, export only the fields needed for the task, remove secrets and unnecessary personal data, and review the model provider's data handling. Remember that local sessions, memory, and skills are retained information too. A procedure can accidentally preserve a customer identifier or an internal endpoint just as readily as it can preserve a useful calculation.

Messaging and scheduling add another dimension: who can start work, and whether anyone is there to review the next step. Hermes's gateway uses allowlists or pairing to control access. Its documented admin/user distinction currently gates slash commands; it should not be mistaken for comprehensive tool authorization for ordinary chat. Keep the first connected workflow limited to producing a report for review. Gateway access controls.

If you later schedule that report, specify the input location, time zone, output destination, and what should happen when data is missing. Check the actual job and execution records. An always-on assistant is now another service to operate, with a model dependency, a scheduler, retained state, and a bill.

Where OpenShell fits

Hermes is the assistant doing the work. OpenShell can supply the controlled environment around it, enforcing filesystem, process, network, and inference access outside the model's reasoning. Hermes explicitly documents whole-process wrapping with OpenShell. NVIDIA also provides a Hermes integration through NemoClaw, whose blueprint supplies the agent image, policies, and inference setup. Hermes security policy and NVIDIA's Hermes integration architecture.

That route becomes relevant when an assistant needs real APIs or incoming messages and you want enforced rules about what it can reach. It is a separate deployment choice, with its own compatible versions and provider configuration. Selecting Docker in Hermes setup does not reproduce the complete NVIDIA integration, and Hermes does not require OpenShell for the basic CLI lab.

The OpenShell guide's policy exercise shows how to distinguish a request the runtime permits from one it denies. Its credential section explains how provider-managed keys can stay outside the workload. Those controls limit access. They cannot establish whether a runbook comparison or freshness report is correct.

Troubleshooting without changing five things at once

The useful first question is where the work stopped: starting Hermes, reaching the model, using a tool, or producing a trustworthy result. Those are different failures and deserve different fixes.

These checks follow the CLI reference, tool selection, memory configuration, and scheduler diagnostics.

hermes doctor is the general installation diagnostic. Check its output for configuration or account information before sharing it. Use /usage when a run becomes unexpectedly expensive, and inspect what the agent is repeatedly reading or trying rather than assuming the final answer's length explains the cost.

For upgrades, follow the instructions for the installation method you actually used. A desktop-managed installation and a source checkout need not have the same update owner. Preserve the configuration and reviewed skills you care about, then repeat the small fixtures after changing the agent, model, or procedure. For a persistent assistant, maintenance includes the knowledge it has accumulated as well as the software package.

Hermes is worth understanding because it connects today's work to tomorrow's starting point. The report gives you something to inspect now; the skill saves you from explaining the method again. When fresh inputs change the answer in the right way, that continuity is doing useful work. When they do not, you have a small, visible problem to fix before it becomes a scheduled one.