How do you set up Hermes Agent?

Hermes Agent is an open-source personal agent from the AI lab Nous Research. It runs in your terminal, can be reached from chat apps, and does work for you with tools such as web search, file editing and shell commands. Its distinctive feature is skills: plain-text instruction files that the agent can read, follow, and even write for itself as it learns.

Setup takes a few minutes. Doing it safely takes a few more, and that is the part this guide spends time on.

Step 1: Install it

Hermes supports Linux, macOS and WSL2, Microsoft's Linux layer for Windows; Windows users set up WSL2 first and run everything inside it. The official installer is a script from the project's GitHub repository. Download it, look through it, then run it:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh
less install.sh
bash install.sh
source ~/.bashrc        # or: source ~/.zshrc on a Mac

If you can, install it under a separate user account or on a spare machine, so the agent never sees your personal files or browser logins. The security guide is explicit on one point: never run it as the root (administrator) user.

Step 2: Choose a model

Hermes does not include its own brain; it calls a language model through a provider. Run:

hermes model

The menu offers many providers, including Nous Portal, OpenRouter, Anthropic, DeepSeek, Hugging Face, and any OpenAI-compatible server such as a local Ollama install. If you use an API key, create a new one just for the agent and set a spending cap with the provider. Hermes keeps keys in ~/.hermes/.env; make that file readable only by you:

chmod 600 ~/.hermes/.env

Step 3: Put its commands in a sandbox

By default the terminal tool runs commands directly on your computer. Hermes then asks before anything on its list of dangerous patterns, which is the manual approval mode. Keep it that way, and don't use the --yolo flag or /yolo command, which switch those prompts off.

Better still, move command execution into a Docker container, an isolated box with its own files:

hermes config set terminal.backend docker

Hermes starts these containers with every Linux privilege dropped and a cap on the number of processes. One trade-off: with Docker as the boundary, it skips the per-command approval prompts, so be careful about which secrets you forward into the container, because anything you pass in can be read by code running there.

Now start a session and look around:

hermes

The welcome banner lists your model, tools and installed skills. Type /tools to see what it can use, and run hermes doctor if something looks wrong.

Step 4: Connect a chat app, carefully

To message the agent from your phone, run hermes gateway setup and pick one platform, Telegram for instance. On messaging platforms Hermes denies everyone by default. Unknown people who write to it get an eight-character pairing code, and nothing happens until you approve them:

hermes pairing list
hermes pairing approve telegram ABC12DEF

Approve only yourself. Avoid the "allow all users" settings entirely.

Step 5: Write your first skill

A skill is a folder containing a SKILL.md file in ~/.hermes/skills/. Writing one by hand is the clearest way to see how the system works. Create ~/.hermes/skills/writing/meeting-notes/SKILL.md:

---
name: meeting-notes
description: Turn rough meeting notes into a short summary with decisions and action items
version: 1.0.0
---

# Meeting notes

## When to Use
The user pastes rough notes from a meeting and asks for a summary.

## Procedure
1. List the decisions made, one line each.
2. List action items as "Person: task (deadline)". Write "no deadline" if none is given.
3. Add open questions at the end.
4. Keep the whole summary under 150 words.

## Pitfalls
- Never invent names or dates that are not in the notes.

## Verification
Every action item names a person from the notes.

Each installed skill becomes a slash command, so in a new session you can type /meeting-notes and paste your notes. The agent loads the full skill only when it needs it, which keeps each conversation short.

How does it learn new skills?

There are two routes. The first is learning from experience. Hermes has a built-in tool that lets the agent create, edit or delete its own skills. According to the documentation, it tends to save a new skill after finishing a complex task that took five or more tool calls, after working its way past errors, or after you correct its approach. The result is an ordinary SKILL.md file in the same folder as yours. The documentation calls this the agent's procedural memory: a written record of how to do something, rather than a fact about you.

That makes the skills folder worth reviewing. Open new skills from time to time, read the procedure, and fix or delete anything wrong, because the agent will follow it next time.

The second route is installing skills written by others from the Skills Hub. Preview first, then install:

hermes skills inspect openai/skills/k8s
hermes skills install openai/skills/k8s

Installation runs a security scan for signs of data theft, prompt injection and destructive commands. Skills from community sources get a stricter policy than official ones, and a "dangerous" verdict cannot be overridden even with --force. A scan is a filter, not a guarantee, so read any third-party skill before you rely on it, and run hermes skills audit to re-check what you have installed.