How to Set Up Hermes Agent Without Losing the Plot

Hermes Agent is easiest to understand if you do not treat it as another chatbot window. It is closer to a small operating layer for AI work: a command-line agent, a tool runner, a memory system, a skills library, and optionally a messaging gateway that lets the same agent talk to you from places like Telegram, Discord, Slack, WhatsApp, or the desktop app.

By the end of this guide you should have Hermes installed, pointed at a model provider, able to run a first task, and set up in a way that will improve over time instead of becoming a forgetful one-off assistant. The goal is not to turn on every feature. The goal is to get a clean first install that you can actually trust and extend.

What you are setting up

Hermes Agent is an open-source agent from Nous Research. The project describes it as a self-improving AI agent with persistent memory, agent-created skills, a terminal interface, a messaging gateway, scheduled automations, and support for many model providers. In practice, that means you can ask it to do real work on your machine: inspect files, run commands, search the web, write code, keep notes, generate images if configured, and remember durable preferences across sessions.

The important design choice is that Hermes is not tied to one model. You can use Nous Portal, OpenRouter, Anthropic, OpenAI, Google, or another OpenAI-compatible provider. That matters because the agent framework and your workflow survive model changes. If one provider is expensive, down, or bad at a specific task, you can switch without rebuilding your whole setup.

It also has two forms of memory that are worth separating early:

• Memory is for durable facts and preferences: who you are, how you like work delivered, stable environment details, and corrections you do not want to repeat.
• Skills are reusable procedures: how to deploy a site, how to debug a particular system, how to write a certain kind of article, or how to avoid a failure that happened before.

That split is one of the best reasons to use Hermes. If you put everything into memory, it gets bloated. If you put repeatable procedures into skills, the agent can load the right playbook only when it needs it.

Before you start

You need a machine where you are comfortable running shell commands. The official docs cover Linux, macOS, WSL2, Android via Termux, and native Windows. On non-Windows systems, the installer expects Git, and on Linux you should also have curl and xz-utils. The installer handles the rest: Python, Node.js, ripgrep, ffmpeg, the virtual environment, and the hermes command.

You also need a model provider. The easiest path is Nous Portal because it can cover models and tool gateway features from one account. If you already have OpenRouter, Anthropic, OpenAI, Google Gemini, or another provider, that works too. Do not over-optimize the first model choice. Pick one reliable model, get Hermes working, then tune cost and quality later.

Decide where you want Hermes to live:

• Local laptop: simplest for learning and code work on your own machine.
• VPS: better if you want Telegram access, scheduled jobs, or an agent that keeps running when your laptop is off.
• Desktop app connected to a backend: useful if you want a GUI but still want the same persistent agent state.

For a first setup, start with the CLI. It gives the most direct feedback and makes troubleshooting easier.

Install Hermes

For Linux, macOS, WSL2, or Termux, the official command is:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

For native Windows, run this in PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

After installation, reload your shell and start Hermes:

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

If the command is not found, open a new terminal first. If it still is not found, the install likely succeeded but your shell path did not update. Check the installer output for the install location and either reload the shell config or call the full path directly.

You can also verify the install with:

hermes --version
hermes doctor

On the test machine used for this draft, hermes --version reported Hermes Agent v0.18.2 with the install directory at /usr/local/lib/hermes-agent. Your version will probably differ. That is fine; the important thing is that hermes --version exits cleanly and hermes doctor does not show a blocking setup error.

Choose a model and provider

Run the setup wizard if this is a fresh install:

hermes setup

Or go straight to the model picker:

hermes model

If you use an API-key provider, Hermes stores secrets separately from normal configuration. You can also set config values directly:

hermes config
hermes config edit
hermes config set model.provider openrouter

The exact provider value depends on your setup, so prefer the interactive picker the first time. The point is to avoid hand-editing a half-correct config before you have seen Hermes run successfully.

A good first model is one that is strong at tool use and coding, not just chat. Hermes can search, read files, patch files, run tests, and call tools, so a model that follows multi-step instructions reliably is worth more than a slightly cheaper model that drops context.

Run your first useful task

Start with a harmless task that uses tools but cannot damage anything:

hermes chat -q "Check what operating system this machine is running and summarize it in one sentence."

That tests the model connection, the terminal tool, and the basic agent loop. Then try a project-local task inside a directory you understand:

cd ~/my-project
hermes chat -q "Read the README and tell me how to run the tests. Do not change files."

This is the right shape for early trust-building. Do not begin by asking a new agent to refactor a production app. Ask it to inspect, explain, and verify. Once it proves it can see the same files and run the same commands you can, let it make a small change.

Enable the tools you actually need

Hermes has toolsets for web search, browser automation, terminal commands, file editing, code execution, image generation, text-to-speech, memory, sessions, delegation, cron, messaging, and more. More tools are not automatically better. Every enabled tool expands what the agent can do and what it must reason about.

Use the tools interface:

hermes tools
hermes tools list

For a practical first setup, enable these if they are available:

• terminal: lets Hermes run commands and verify results.
• file: lets Hermes read, write, search, and patch files.
• web: lets Hermes search and extract current docs.
• memory: lets Hermes remember durable preferences.
• skills: lets Hermes load reusable procedures.
• session_search: lets Hermes find prior conversations.

Leave specialized tools off until you need them. Image generation, smart home, Discord admin, or browser automation can be added later. After changing tool availability, start a new session so the active tool schema matches the config.

Set up memory without making a junk drawer

The fastest way to ruin agent memory is to save everything. Hermes memory should hold facts that will still be useful later: your preferred communication style, stable environment details, project conventions, and corrections that prevent repeated mistakes.

Good memory examples:

• “User prefers concise status updates on Telegram.”
• “Project X uses pytest and requires a database fixture before integration tests.”
• “The production site is deployed through Cloudflare Tunnel, not direct DNS to the app.”

Bad memory examples:

• “Fixed bug 123 today.”
• “Published draft version 4.”
• “Need to check the thing tomorrow.”

Those belong in issue trackers, handoff files, session history, or project docs. Memory is for durable context, not a running diary.

When Hermes completes a complex task, it may offer to save either a memory or a skill. Say yes when the lesson will matter again. Say no when it is only a temporary task state.

Use skills for repeatable work

Skills are where Hermes gets unusually useful. A skill is a compact procedure the agent can load when a task matches. For example, a site deployment skill can encode where the repo lives, what tests to run, what cache issues to watch for, and how to verify the live URL. A writing skill can encode tone, structure, source rules, and publishing checks.

Check installed skills with:

hermes skills list
hermes skills browse

A healthy skill should answer:

• When should this be used?
• What exact steps should the agent follow?
• What mistakes have happened before?
• How does the agent verify the job is actually done?

That last question matters. A skill that says “deploy the site” is weak. A skill that says “build, run tests, deploy, curl the live URL, and confirm the expected title appears” changes behavior.

Add messaging only after the CLI works

Hermes can run through a gateway on platforms like Telegram, Discord, Slack, WhatsApp, Signal, Matrix, email, SMS, and others. That is powerful because your agent can keep working on a VPS while you talk to it from your phone.

But set up messaging after the CLI works. Otherwise you will not know whether a failure is the model, the config, the gateway, the platform token, or the chat authorization layer.

The gateway commands are:

hermes gateway setup
hermes gateway run
hermes gateway status

For a persistent server install, use the service/background mode documented by Hermes for your platform. On a VPS, you want a gateway that survives logout and restarts cleanly. After it connects, send a small test message from the platform and confirm Hermes can answer and use basic tools.

How to know Hermes is working

A working first setup should pass these checks:

hermes --version
hermes doctor
hermes config
hermes tools list
hermes chat -q "Say which model/provider you are using and then stop."

Then verify one real tool task:

hermes chat -q "Run pwd and date, then summarize the result."

If Hermes can answer, run commands, and remember a preference in a future session, the base install is working.

Common failures and fixes

Symptom	Likely cause	Fix
hermes: command not found	Shell path did not reload	Open a new terminal or source your shell config
Model calls fail	Missing or wrong provider credentials	Run hermes model, hermes setup, or check the provider API key
Tool is unavailable	Toolset disabled or missing dependency	Run hermes tools list, enable the tool, then restart the session
Config change seems ignored	Active session cached old config	Start a new Hermes session or restart the gateway
Gateway connects but does not answer	Platform token/auth/session issue	Check hermes gateway status and gateway logs
Agent keeps forgetting procedures	Procedure was saved as memory or not saved at all	Turn repeatable workflows into skills
Memory becomes noisy	Temporary task notes were saved	Keep task state in files/issues, not durable memory

How to make Hermes better over time

The first week with Hermes should be about teaching it your operating style. Correct it when it guesses. Ask it to explain how it verified something. When it solves a non-trivial problem, save the method as a skill. When it learns a stable preference, save a short memory. When a skill proves wrong, patch the skill immediately.

This creates the loop Hermes is built for: do work, discover a sharp edge, write down the sharp edge in the right place, and avoid repeating the mistake next time.

When not to use Hermes

Do not use Hermes as a blind autopilot for systems you do not understand. Do not give it broad destructive permissions on day one. Do not ask it to manage secrets unless you have checked how your install stores and redacts them. Do not replace tests, logs, or deployment verification with “the agent said it worked.”

Use Hermes when the work benefits from memory, tools, and follow-through. Start with inspection and small changes. Build trust from real verification.

Sources

This guide is based on the official Hermes Agent documentation, the Hermes Agent GitHub README, and live CLI checks against an installed Hermes Agent environment. The public commands and install paths above come from the official docs; the version check is an example from the test environment and should not be treated as the current latest version.