Hermes Agent is the open-source autonomous AI agent from Nous Research — an agent that lives where you install it (local workstation, €5 VPS, GPU cluster or serverless infra), that learns from usage, that creates its own skills after solving a complex task and that stays reachable from Telegram, WhatsApp, Discord, Slack, Signal or email — all under a single MIT license.
This tutorial is a vendor-neutral guide: commands come from the official GitHub README and the official documentation. Nothing is invented. By the end, you'll have a working customer-reception agent on Telegram — and you'll know how to secure it properly.
What it is not
Hermes Agent is not an IDE copilot, not a wrapper around a single cloud API, not a plain chatbot. It's an autonomous agent that gains capability over time through a native learning loop (auto-created skills, persistent memory, a user model that sharpens session after session).
Essential vocabulary
Before installing anything, let's align on vocabulary. Without these basics, the official documentation feels confusing on a first read.
| Term | What it means in practice |
|---|---|
| Assistant vs agent | An assistant understands and answers. An agent executes actions (calendar, CRM, sending emails, API calls). Hermes is an agent. |
| SOUL.md | Markdown file that defines the agent's personality: tone, conversation rules, boundaries. It's the first file you write and the most important. |
| Skill | Procedural capability the agent creates automatically after a complex task — then reuses and refines through usage. Lives in ~/.hermes/skills/. |
| Persistent memory | MEMORY.md (general memory) and USER.md (user model). Persists across sessions. |
| Gateway | Process that connects the agent to messaging platforms (Telegram, WhatsApp, Discord, etc.). A single gateway drives every channel. |
| Sub-agent | Isolated sub-agent Hermes can spawn to parallelize a workstream (without consuming context in the main session). |
| MCP | Model Context Protocol — standard for plugging third-party tool servers into Hermes. Clean scope extension without hacking the core. |
| Tool Gateway (Nous Portal) | Bundle of 4 managed tools (web search, image generation, TTS, browser) accessible via OAuth through hermes setup --portal. |
| Provider | LLM model provider. Anthropic, OpenAI, OpenRouter, Ollama (local), ElevenLabs (TTS), Nous Portal. |
Choosing your infrastructure
Direct answer. For most small-business use cases, a Linux VPS at €5-10/month (Hetzner, OVH, Scaleway) is more than enough. Hermes runs fine with 1 vCPU and 2 GB of RAM as long as the LLM model stays remote (cloud).
Local machine (Linux/macOS/WSL2/native Windows)
Free, zero external dependency. Ideal for testing. Trade-off: the agent only runs while the machine is on, so cron tasks scheduled at night won't execute.
VPS at €5-10/month — recommended for production
Hermes runs continuously, the messaging gateway stays reachable, the cron scheduler fires even at night. Back up ~/.hermes/ regularly.
Serverless (Daytona, Modal, etc.)
Near-zero cost when the agent is idle. More complex to set up — worth it if you already run serverless workflows. See the official docs for concrete integrations.
Choosing your LLM provider
| Provider | Token cost | Confidentiality | Notes |
|---|---|---|---|
| OpenRouter | Multi-model à la carte, pay-as-you-go | Depends on the selected model | Convenient for testing multiple models quickly. |
| Anthropic (Claude) | Direct Anthropic billing | DPA available | Excellent on long, agentic tasks. |
| OpenAI (GPT) | Direct OpenAI billing | DPA available | Multimodal models, very strong tool ecosystem. |
| Ollama (local) | Free in tokens | 100% local — no outbound data | Requires CPU/GPU. Ideal for strict GDPR deployments. |
| Nous Portal | Turnkey OAuth | Transits through Nous Research infra | Ultra-fast setup via hermes setup --portal. |
Sufficient context window, or truncation
Pick a model with a large context window (ideally 100k tokens or more). Otherwise your sessions get truncated mid-task and the agent loses the thread. Claude Sonnet 4+, GPT-4.1+ and recent OpenRouter models are comfortable on this front.
Installing Hermes Agent in one command
Direct answer. A single command line, depending on your OS. The two one-liners below are taken verbatim from the official documentation.
Linux, macOS, WSL2, Android (Termux)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Native Windows (PowerShell)
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
The installer downloads and sets up uv (Astral's Python package manager), Python 3.11 in an isolated venv, Node.js, ripgrep, ffmpeg, and on Windows a portable Git Bash (MinGit) — all inside %LOCALAPPDATA%\hermes\ without admin rights.
The main directory ($HERMES_HOME) is:
- Linux / macOS / WSL2 →
~/.hermes/ - Native Windows →
%LOCALAPPDATA%\hermes\
Windows Defender blocking uv.exe: it's a false positive
Some antivirus software (Windows Defender, Bitdefender) flags uv.exe as malware. It's an erroneous heuristic detection on an unsigned Rust binary. The official documentation offers cryptographic verification via gh attestation verify. Whitelist the %LOCALAPPDATA%\hermes\bin\ folder, not the hash — Hermes updates uv and the hash changes with each release.
Running the setup wizard
hermes setup
This interactive wizard asks you to pick a provider, a model, the enabled tools and optionally a messaging platform. It also auto-detects a ~/.openclaw folder and offers migration (see below).
Shortcut — if you want the fastest path to a talking agent:
hermes setup --portal
This variant triggers an OAuth connection to Nous Portal that gives you access to a model plus the four managed tools (web search, image generation, TTS, browser) in a single sign-in.
First launch — the TUI
Once setup is done:
hermes
You're in the TUI (Terminal User Interface) and can start talking to the agent. A few slash commands worth knowing from day one:
| Command | What it does |
|---|---|
/new or /reset | Start a new conversation |
/model claude:sonnet-4 | Switch model without leaving the TUI |
/personality [name] | Load an alternative personality |
/skills | List available skills |
/usage | View token consumption |
/compress | Compress the session context |
/insights --days 7 | LLM summary of the last 7 days of sessions |
/stop | Interrupt the current task |
All personality and memory now live under $HERMES_HOME. Back up that folder — it is your agent.
Writing your SOUL.md — the personality file
Direct answer. SOUL.md is a Markdown file you write by hand to define the tone, the conversation rules and the boundaries of the agent. It's the most important file in the system.
Tutorial's running example: a customer-reception agent for a small business that qualifies incoming requests and offers an appointment. Here's a minimal but functional SOUL.md:
# SOUL.md — "MAG&Cie" reception agent
## Role
You are the reception agent for MAG&Cie, a technology consulting firm in Nantes.
Your goal is to:
1. Understand the visitor's request in 2 to 3 messages max.
2. Qualify their need (small business / SMB, topic: cyber, AI, dev, other).
3. Offer a free discovery appointment or point to the relevant resource.
## Tone and style
- Warm but direct, never pompous.
- English by default, informal register only if the visitor uses it first.
- Short sentences. Zero unnecessary jargon.
- Emojis: maximum one per message, only when it adds something.
## Rules
- Never promise deadlines or pricing. Refer to the MAG&Cie team for any quote.
- Never guess: if you don't know, say so and offer human contact.
- Visitor data is only used for the current conversation.
## Available resources
- Contact page: https://www.mag-cie.com/en/contact/
- Book an appointment: https://www.mag-cie.com/en/rendez-vous/
- AI assistants: https://www.mag-cie.com/en/assistants-ia/
- Cyber audit: https://www.mag-cie.com/en/audit-cybersecurite/
Place this file at the root of $HERMES_HOME/. Hermes loads it automatically at startup. You can also create multiple personalities and switch via /personality [name].
Best practice — short SOUL.md wins
A long SOUL.md ends up diluting the key instructions. Stay under 150-200 lines total. If you need to add rules, split them into separate context files (see the context files concept in the official docs).
Connecting Telegram, step by step
This is the most-searched section. Let's take it calmly.
Create a Telegram bot via BotFather
In Telegram, search for @BotFather and start a conversation. Send /newbot, provide a display name then a unique identifier ending in _bot. BotFather returns an HTTP API token — that's the secret to protect.
Run the gateway setup on the Hermes side
In your terminal: hermes gateway setup. Select Telegram, paste the token when asked. Hermes stores it in its encrypted configuration (never put it in a committed file).
Start the gateway in the background
hermes gateway start. The process stays open and listens for incoming messages. On a VPS, run it under systemd or tmux so it survives SSH disconnection.
Send the first message to the bot
Open your bot in Telegram, write "hello". The agent replies based on the SOUL.md you defined. Then try the slash commands: /model, /skills, /usage, /stop.
Never commit the bot token
The BotFather token gives full control over your bot. If you commit it to GitHub, it gets scraped by bots within minutes and your agent can become a spam vector. Always store it as an environment variable or in a vault (1Password, Bitwarden, Vault, age, sops).
Other messaging platforms — same mechanics
The gateway drives multiple channels from a single process: Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams. Each has its own setup steps (documented in the official Messaging Gateway guide), but the pattern stays hermes gateway setup → follow the instructions → hermes gateway start.
Skills and memory — the learning loop
Direct answer. Hermes creates skills automatically after solving a complex task and self-improves them through usage. This is the heart of the "self-improving agent" positioning Nous Research claims.
- Skills (
~/.hermes/skills/): procedural memory. Reused automatically when a similar situation arises. You can also write them manually — the format is documented on agentskills.io, the open standard Hermes follows. - General memory (
MEMORY.md): durable facts. Hermes self-nudges to persist what should be persisted. - User model (
USER.md): Hermes progressively builds a representation of who you are (dialectical model via Honcho). This understanding sharpens session after session. - Cross-session search: FTS5 full-text search over every past conversation, with LLM summary on demand.
To write a skill manually, create a .md file in ~/.hermes/skills/ following the documented format. Each skill has a name, a usage description and procedural instructions the agent applies when the description matches the current situation.
Automating — the cron scheduler
Direct answer. Hermes ships a native cron scheduler that executes recurring tasks in natural language and delivers the result on any platform (Telegram, Discord, email…). No external tool required.
Realistic examples for a small business:
- "Every Monday at 9am, summarize the client emails received over the weekend and send me the digest on Telegram."
- "Every night at 3am, back up the contents of
~/.hermes/to my remote storage." - "On the 1st of every month, check that my domain names expire in more than 30 days and alert me otherwise."
Configuration happens via hermes in an interactive session: describe the task, Hermes creates the cron entry for you. See the official cron documentation for management (list, disable, history).
Extending the agent — MCP integration
Hermes connects natively to any MCP server (Model Context Protocol) — Anthropic's open standard for plugging third-party tools into an LLM agent. Concretely: your CRM, your calendar, your internal knowledge base, your ticketing system.
Two possible moves:
- Consume an existing MCP server (e.g. Google Calendar, HubSpot, Notion). See the list of available MCP servers — the Hermes-side integration takes a few lines of configuration.
- Build a custom MCP server for your line-of-business tools. That's precisely our MAG&Cie MCP creation offering if you want to delegate.
Security — the non-negotiable section
Direct answer. A self-hosted agent that can send emails, call APIs and execute shell commands is a strategic asset and an attack surface. What you don't secure becomes the entry point for the next incident. This section wears the MAG&Cie CISO hat — most competing tutorials devote less than three lines to it.
Command approval
Hermes natively provides a command approval system: any shell command executed by the agent can require explicit human confirmation. Enable it on dangerous patterns (rm, curl | bash, anything modifying /etc or escaping the sandbox). See the Security → Command approval doc.
DM pairing
On messaging platforms, only paired users can talk to the agent. A stranger's first message triggers nothing until pairing is explicitly approved. Enable it from the first deployment, it's not a comfort option.
Container isolation
The repo ships ready-to-use docker-compose.yml files. Isolate the agent in a container with a non-root user, a read-only filesystem except /tmp and $HERMES_HOME, and no network access to the intranet.
Prompt injection: least privilege
An agent reading the web or emails can receive malicious instructions hidden in the content it ingests. Baseline principle: only enable strictly necessary tools. A customer-reception agent doesn't need terminal access, doesn't need to read your emails, and doesn't need write access to your CRM.
Secrets out of config
Every API key (LLM, Telegram, CRM…) must live in environment variables or a vault (Vault, age, sops). Never in cleartext inside a versioned config file. Check with git secrets or gitleaks before the first push.
Reduced network exposure
The gateway doesn't need to be reachable from the Internet — it's Telegram/Discord/etc. that push messages via long-polling or webhooks. If you do expose a port, put TLS in front, add auth and a firewall that restricts incoming IPs. Regular updates (hermes update) for security patches.
GDPR — where does the data live?
All conversation data transits through the LLM provider you choose. Under your contractual terms with that provider — not those of Nous Research (except if you use Nous Portal, in which case only that portion transits through their infra). For a strict GDPR deployment: prefer local Ollama (100% on-premise) or a provider with a DPA and EU localization, apply minimization (don't let the agent copy personal data into MEMORY.md unnecessarily) and document this flow in your records of processing activities. A MAG&Cie cybersecurity audit validates the compliance of an existing deployment.
Migrating from OpenClaw
If you're coming from OpenClaw, Hermes automatically imports the essentials:
hermes claw migrate # Interactive migration (full preset)
hermes claw migrate --dry-run # Preview what would be migrated, without touching anything
hermes claw migrate --preset user-data # Migration without secrets (API keys)
hermes claw migrate --overwrite # Overwrite conflicting files
What gets imported: SOUL.md, memories (MEMORY.md, USER.md), user skills, the command allowlist, messaging configuration, allowlisted API keys (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs) and workspace instructions (AGENTS.md).
The most common pitfalls
1 — Model with too small a context window
On long tasks, a model capped at 32k tokens truncates mid-session and the agent loses the thread. Choose a 100k+ model (Claude Sonnet 4+, GPT-4.1+, Gemini 2, recent DeepSeek Chat).
2 — Agent running as root
On a VPS, never run Hermes as root. Create a dedicated user (useradd hermes-agent), grant it only the necessary rights, run the gateway under that user.
3 — Skipping updates
Hermes moves fast (v0.18.0 released July 1, 2026). Run hermes update regularly, watch the GitHub repo, apply security patches quickly.
4 — Over-permissioning tools from day one
Don't enable all 60+ built-in tools at once. Start with the strict minimum (send message, read a doc). Add on demand, one by one. Every enabled tool is an extra attack surface.
5 — Gateway exposed without authentication
If you open a port for a webhook, add authentication (shared secret, mTLS) and a firewall restricting source IPs. A gateway exposed without auth is a potential Trojan horse.
6 — Antivirus silently blocking `uv.exe`
On Windows, if the installation fails mysteriously, check that Defender or Bitdefender hasn't quarantined uv.exe. Whitelist the %LOCALAPPDATA%\hermes\bin\ folder, not the hash.
Production checklist
Before opening your agent to real users:
Before go-live
- Installation verified with
hermes doctor— no errors, no red warnings. -
SOUL.mdreviewed, tested on a dozen plausible + adversarial scenarios. - LLM provider configured, API key in an environment variable or vault (never hardcoded).
- Telegram gateway (or other) tested end-to-end — send, receive, slash commands.
- Command approval enabled on dangerous shell commands.
- DM pairing enabled — only approved users can talk to the agent.
- Docker isolation in place (non-root user, mostly read-only FS, restricted network).
- Cron scheduler configured (if recurring tasks) + logs monitored.
- Daily backup of
$HERMES_HOMEto encrypted remote storage. -
hermes updatescheduled regularly (monthly cron + release watch). -
SOUL.md,MEMORY.md,USER.md,~/.hermes/skills/files backed up separately. - GDPR register up to date — LLM provider, data sent, legal basis, retention period.
Real-world costs
- Software — free (MIT license).
- Hosting — €0 if you run it locally, ~€5-10/month if you take a dedicated Linux VPS.
- LLM tokens — variable depending on usage. For a small-business reception agent with ~200 conversations/month on Claude Sonnet, expect a few dozen euros/month. For local Ollama use with an 8B model on your own GPU: €0 in tokens.
- Backups — a few GB/month on storage like Backblaze B2 or Wasabi. Negligible.
Want turnkey support? Two MAG&Cie options
This tutorial lets you deploy and secure Hermes Agent yourself. If you'd rather delegate or want a pre-secured deployment, here are two MAG&Cie offerings that naturally extend this guide:
Operational AI assistant, without managing the infrastructure
Want an assistant on Telegram or WhatsApp that works tomorrow, without spending a day running a gateway? That's exactly the scope of our custom AI Assistants offering: setup, hosting and monitoring managed by MAG&Cie, starting at €150 (excl. VAT) + €20 (excl. VAT)/month.
Audit or harden an existing deployment
Already installed Hermes (or another agent) and want an external CISO perspective on security? Our small business / SMB cybersecurity audit covers self-hosted agents: network posture, isolation, secret management, GDPR, prompt injection. For structured integration into your processes, see also the MAG&Cie AI support offering.
Going further
- Official Hermes Agent documentation — the up-to-date reference, release after release.
- NousResearch/hermes-agent GitHub repo — source code, releases, issues, SECURITY.md.
- agentskills.io — the open skills standard, Hermes-compatible.
- Available MCP servers — a catalog of ready-to-use connectors.
- MAG&Cie tutorial: adding Google/Microsoft SSO to your application — to secure human access to an application that Hermes drives.
All commands in this tutorial come from the official Hermes Agent documentation and the Nous Research GitHub repo README as of July 2, 2026 (Hermes Agent v0.18.0). Verify the official documentation before any deployment — the project moves fast.