Hermes Agent: what it is, and how to start
Updated on
Hermes Agent is an open-source agent from Nous Research that you install and run yourself. It can chat in a terminal, connect to messaging apps, and keep skills and memory between sessions. This page follows the project's own docs for what it is and how a first run is supposed to go.
Status: Not tested yet. We have not run Hermes Agent for this page, so nothing here is from our own use. The docs and the GitHub release list were checked on 2026-10-31. The latest release that day was v0.22.5, published on 2026-10-23.
What Hermes Agent is
Hermes Agent is an open-source AI agent built by Nous Research. The project's own tagline is "the agent that grows with you": it saves what it learns as skills and memory, and builds a picture of how you work across sessions. The code is on GitHub at NousResearch/hermes-agent under the MIT license.
Unlike a hosted assistant, you install Hermes yourself and pick the model it uses. It can run on your laptop, a small VPS or a cloud sandbox, and you can talk to it in a terminal or from a chat app such as Telegram while it works somewhere else. On 2026-10-31 the latest GitHub release was v0.22.5, published 2026-10-23. hermes update moves an install to the latest stable release.
What it can do
- Skills it writes itself. After a complex task, Hermes can save the workflow as a skill in
~/.hermes/skills/and improve it on later runs. Skills are compatible with the agentskills.io open standard. - Memory across sessions. Two small files,
MEMORY.md(about 2,200 characters) andUSER.md(about 1,375), hold notes about your work and about you. They load at the start of a session, so something saved today shows up in the next session, not the current one. Hermes can also search its own past conversations. - A messaging gateway. One background process connects Hermes to Telegram, Discord, Slack, WhatsApp, Signal, email and more. You don't need any of them to use the terminal.
- Scheduled jobs. A built-in cron scheduler takes plain-language schedules ("every 6h") and can deliver the result back to a chat.
- Places to run commands. Six built-in terminal backends: local, Docker, SSH, Modal, Daytona and Vercel Sandbox. Daytona and Modal can hibernate when idle.
- Subagents. Hermes can spawn isolated subagents for parallel work.
- Any model provider.
hermes modelswitches between Nous Portal, Anthropic, OpenAI (including a Codex login), OpenRouter, xAI, or a local OpenAI-compatible server such as Ollama or vLLM. The model needs at least 64,000 tokens of context. Nous Portal is the shortcut: one login for 300+ models plus a Tool Gateway for web search, image generation, text-to-speech and a cloud browser.
Prices are left out on purpose. See Nous Portal and the providers doc.
What you need
| Need | Required | What the docs say |
|---|---|---|
| A supported computer | Yes | Linux, macOS, WSL2, or native Windows. Android aarch64 uses Termux instead. The macOS installer is Apple Silicon only. |
| A model provider | Yes | An API key, OAuth, or a local OpenAI-compatible endpoint, with at least 64,000 tokens of context. |
| A messaging credential | No | Only for a chat app. Example: TELEGRAM_BOT_TOKEN. |
The Linux and macOS install script needs Git, curl, tar and SHA-256 tools, and sets up Python 3.14, Node.js, ripgrep and FFmpeg for you. Intel Macs are not a supported platform. Your data lives in ~/.hermes (or %LOCALAPPDATA%\hermes on native Windows).
Install and first run
Get one chat working before a gateway, cron, or skills. If Hermes cannot complete a normal chat, do not add more features yet.
Install
On Linux, macOS, or WSL2, run the project install script. On native Windows, run the PowerShell installer. Then reload the shell.
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
source ~/.bashrc # or: source ~/.zshrc
hermes
The quickstart calls the Desktop installer the recommended macOS and Windows path when you want the app too. POSIX data defaults to ~/.hermes/, and the wrapper is ~/.local/bin/hermes. hermes doctor is the README's check command.
Pick a model
Run hermes model and pick a provider, or run hermes setup --portal to sign in to Nous Portal and turn on its Tool Gateway.
hermes model
hermes setup --portal
hermes setup has three modes. Quick Setup is Portal. Full Setup is bring-your-own keys. Blank Slate keeps a provider, a model, file tools, and the terminal, and leaves web, memory, cron, skills, and MCP off. Secrets go in ~/.hermes/.env. Other settings go in ~/.hermes/config.yaml.
Start chatting
Start the classic CLI with hermes, or the newer terminal UI with hermes --tui. A working chat shows your model and replies without an error.
hermes
hermes --tui
Both share the same sessions and config. hermes --continue resumes the last session.
Connect a messaging app (gateway)
After a CLI chat works, run hermes gateway setup and then hermes gateway start. Send the bot a message on the platform you configured.
hermes gateway setup
hermes gateway start
Setup is an interactive wizard. The terminal works without a messaging platform. The overview names TELEGRAM_BOT_TOKEN and does not show how to create the token. The wizard section shows arrow-key selection and does not list the fields.
Schedule a job
With the gateway running, schedule a job from the CLI. One documented example is a news scan every six hours. You can skip this step.
The gateway must be running, or agent jobs wait for the next tick after hermes gateway start. The tick is every 60 seconds.
hermes cron create "every 6h" "Scan for news" --continuity
--continuity feeds the job its own last output, so a repeating scan can skip items it already reported. The first run has no previous output. You can also pass --workdir, or ask in chat through cronjob_manage. With no pin and no cron.model, the job follows the main model when it fires.
Security basics
Hermes checks commands against a list of dangerous patterns. Default mode smart uses an auxiliary LLM: low-risk commands pass for that command only, dangerous ones are denied, and unclear ones ask you. manual always asks. off matches --yolo, and the page says to use it only in a trusted environment. Cron and unattended sessions default to deny, which blocks the command.
The gateway denies anyone who is not allowlisted or paired. With no allowlist and no GATEWAY_ALLOW_ALL_USERS, all users are denied. Chat DMs default to pair: the person gets an 8-character code.
hermes pairing approve telegram XKGH5N7P
Codes expire after 1 hour and are never logged to stdout. Email stays on ignore unless pairing is turned on for it. Allowing every user is marked as not recommended when the bot has a terminal.
The docker backend uses --cap-drop ALL, then adds DAC_OVERRIDE, CHOWN, and FOWNER back. It sets no-new-privileges and a process cap of 256. An empty docker_forward_env keeps secrets out of the container. Set the backend with:
hermes config set terminal.backend docker
For a production gateway, the security page recommends one of the isolated backends (docker, modal, daytona or vercel_sandbox) so commands run off your host machine. On the default local backend, commands run directly on your computer.
Moving from OpenClaw or Claude Code
OpenClaw is a separate assistant. Its README says it runs on your own computer and meets you in channels you already use, including Discord, Slack, Telegram, and WhatsApp.
Hermes can import settings, memories, and skills from OpenClaw, Claude Code, Codex CLI, or Cursor. OpenClaw API keys move only if you ask. hermes setup offers this when it finds ~/.openclaw, ~/.claude, ~/.codex, or ~/.cursor, after installing the agent-importers plugin and showing a preview.
hermes plugins install agent-importers
hermes import-agent openclaw --dry-run
hermes import-agent openclaw --migrate-secrets
hermes import-agent claude-code
For OpenClaw, that page lists SOUL.md, memory files, skills under ~/.hermes/skills/openclaw-imports/, and allowlisted keys only with --migrate-secrets. hermes claw migrate is the older command. It does not list which Claude Code files move. See Claude skills in Claude Code for those folders.
Hermes Agent vs a hosted agent like Grok Bot
| Question | Hermes Agent | Grok Bot |
|---|---|---|
| Who runs it | You install it and update it with hermes update. | You use the app. Each Bot has a persistent cloud computer. |
| Where work runs | Your machine, or a backend you choose. A cloud VM is one option in the README. | A cloud computer with a browser, filesystem, and terminal, running in Cursor's cloud. |
| Laptop closed | Depends on where you run it. The README says it is not tied to your laptop: it can live on a VPS or cloud VM while you message it. | Work stays on the cloud computer. Closing the app, laptop, or phone does not stop a background turn or a routine. |
| The model | You pick one and pay its provider. Context must be at least 64,000 tokens. | Comes with the plan that includes Grok Bot; usage draws from that plan. |
| Saved work | Skill files, plus cron in the gateway. | Walk through a path once, save it as a skill, and rerun it on a schedule. |
The trade-off is control versus upkeep. With Hermes you choose the model, the machine and the sandbox, and you install updates and secure the gateway yourself. Grok Bot's docs describe the opposite: setup is a message, not a workflow builder, and every Bot on your account shares one managed cloud computer. See what Grok Bot is, Grok Bot skills, and how Grok Bot routines run.
On cost, Hermes Agent's site calls the software free, but you pay whichever model provider you connect. Grok Bot is included with Premium, Super and Ultra on The X Subscription, and with some legacy Cursor, SuperGrok, X Premium+ and Grok Business plans; the full list is on the plans and billing page. Prices are left out on purpose.
Limits of this guide
- We have not installed Hermes Agent, sent it a chat, opened the gateway or scheduled a job. Everything above comes from the project's README, site and docs, checked on 2026-10-31. If we test it, the run will be logged here with the date, version, machine and output, following how we test.
- Hermes ships often, so commands and defaults can change after v0.22.5. The docs we read don't cover how to create a Telegram bot token or which ChatGPT plans the Codex login accepts.
FAQ
What is Hermes Agent?
Hermes Agent is an open-source agent from Nous Research. You install it and run it yourself. It chats in a terminal, can connect to messaging apps through a gateway, and keeps skills and memory between sessions. The license on the GitHub README is MIT.
Is Hermes Agent free?
The project website calls it a free, open-source AI agent, and the README says the license is MIT. You still need a model provider. That provider can be a paid API or a subscription such as Nous Portal. This page does not list prices.
How do I install Hermes Agent?
On Linux, macOS, or WSL2, the docs give a one-line install script from hermes-agent.nousresearch.com. On native Windows they give a PowerShell one-liner. The macOS desktop installer is Apple Silicon only, and the install page says Intel macOS is not a supported platform. Afterward, reload the shell and run hermes.
Can Hermes Agent use Claude, GPT, or a local model?
The docs say you need at least one provider, and you switch with the hermes model command. They list Nous Portal, Anthropic, an OpenAI Codex login, OpenRouter, an xAI key or xAI OAuth, and a custom endpoint for Ollama, vLLM, or any OpenAI-compatible API. The model needs at least 64,000 tokens of context. Which ChatGPT plan tiers work with the Codex login is not currently documented.
How do I connect Hermes Agent to Telegram?
The docs say to get a normal CLI chat working first, then run hermes gateway setup and hermes gateway start. The messaging page names TELEGRAM_BOT_TOKEN as a credential the gateway reads. Unknown users are denied unless they are on an allowlist or you approve a pairing code. This guide does not repeat the separate Telegram setup page.
How is Hermes Agent different from Grok Bot?
Hermes Agent is software you install and run, and you bring the model. Grok Bot is an app whose Bots work on a persistent cloud computer. The Grok Bot docs say that computer runs in Cursor's cloud, and that closing your laptop does not stop a background turn or a routine. Both can save a way of working and run it again later. We have not run either product for this page.
Related on bests.one
- What is Grok Bot — a hosted agent, for the comparison.
- Grok Bot skills
- How Grok Bot routines run
- Claude skills in Claude Code — the Claude Code side of an import.
- How we test
Sources: Hermes Agent (project site), Hermes Agent README (GitHub), Hermes Agent releases (GitHub), Quickstart (Hermes Agent docs), Installation (Hermes Agent docs), Security (Hermes Agent docs), Skills (Hermes Agent docs), Memory (Hermes Agent docs), Cron (Hermes Agent docs), Providers (Hermes Agent docs), Messaging gateway (Hermes Agent docs), Grok Bot (xAI docs), OpenClaw README (GitHub). Checked on 2026-10-31.