Hermes is an open-source AI agent from Nous Research that runs on your machine, remembers everything, learns skills, and answers you on Telegram, Discord, Slack and more — with full tool access, not just chat. This is the zero-to-useful path, in the order that avoids the classic mistakes.
Hermes isn't a chatbot — it's an agent loop with tools: a terminal, file access, web search, browser automation, scheduled jobs, and persistent memory. The same brain serves every surface: your terminal (hermes), a desktop app, a web dashboard, and a gateway that connects it to messaging platforms. I mostly talk to mine from my phone via Telegram while it works on my always-on box.
Three properties matter for how you set it up:
# one-liner: sets up uv, Python, the venv, and the launcher
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
# sanity check
hermes doctorhermes doctor verifies dependencies and config — run it whenever something feels off; it's the first thing support will ask for anyway.
hermes setup # interactive wizard — model, terminal, gateway, tools
hermes model # just the model/provider picker| Your situation | Good default |
|---|---|
| Want one key for many models | OpenRouter (OPENROUTER_API_KEY) — swap models without new accounts |
| Already pay for ChatGPT/Claude | OAuth via hermes auth add — uses your subscription instead of API billing |
| Want free/cheap for routine work | Google Gemini free tier, DeepSeek, or Kimi — see the cost table in the Optimizing Hermes guide |
| Fully offline | Local model via custom endpoint (llama.cpp, vLLM, Ollama) |
Start with a mid-tier model, not the flagship. Hermes is tool-heavy; most turns are "run command, read output, decide next step" — a good mid-tier model does this at a fraction of the cost, and you can escalate per-task later (that's the whole point of the Optimizing Hermes guide).
Run hermes and have one real conversation. The single highest-leverage thing you can do in the first hour:
"Save to memory: my name, where I'm based, what I work on, how I like answers (direct, no fluff), and the machines/servers I have. Then summarize what you saved."
That memory is injected into every future session. It's the difference between an assistant that asks "what's your server's IP?" every time and one that already knows.
The gateway is Hermes' always-on messaging bridge. Telegram is the fastest to set up:
hermes gateway setup # pick Telegram, paste bot token from @BotFather
hermes gateway install # install as a background service
hermes gateway start
hermes gateway statusMessage your bot, then in that chat run /sethome — this makes it the default delivery target for scheduled jobs and alerts. 20+ platforms are supported (Discord, Slack, WhatsApp, Signal, Matrix, Email...), same pattern.
If the gateway dies when you log out of SSH, enable lingering: sudo loginctl enable-linger $USER. On WSL2 you need systemd=true in /etc/wsl.conf.
hermes tools # interactive picker
hermes tools list # see everythingThe defaults are sane. Worth knowing:
terminal + file are the workhorses — this is what makes Hermes an operator, not a chatbot.browser unlocks headless screenshots and web automation (needs Chromium — Hermes can install Playwright for you).homeassistant is off by default; it auto-activates when HASS_TOKEN is set (see Letting an AI agent run your Home Assistant)./reset), not mid-conversation — that's deliberate, to protect prompt caching.Hermes asks before running destructive commands. Three modes:
hermes config set approvals.mode manual # always ask (default)
hermes config set approvals.mode smart # auto-approve low-risk, ask on dangerous — recommended
hermes config set approvals.mode off # never ask (YOLO — not recommended)Start on manual. Move to smart once you've seen its judgment for a week. Leave secret redaction (security.redact_secrets) on forever — it scrubs API keys from tool output before they reach the model or logs.
Two files shape the agent more than any setting:
~/.hermes/SOUL.md — identity and behavioral rules, loaded every session. Mine says: be direct, have opinions, be resourceful before asking, earn trust through competence. Write yours in your own words.~/.hermes/skills/) — procedural memory. You rarely write these by hand: when Hermes solves something non-trivial, tell it "save that as a skill." Browse community skills with hermes skills browse.Once the gateway is up, scheduled jobs are one sentence away — from Telegram, even:
"Every morning at 8, check [thing you care about] and only message me if something needs attention. Silence is the default."
That's a durable cron job with Telegram delivery — no YAML, no crontab syntax. Manage them with hermes cron list or just ask the agent.
/sethome.~/.hermes/SOUL.md and tune it. Switch approvals to smart if it earned it.| Command | What it does |
|---|---|
hermes | Interactive chat |
hermes chat -q "..." | One-shot query |
hermes setup / hermes model | Wizards: full setup / just the model |
hermes doctor | Health check (run this first when things break) |
hermes gateway run|install|start|status | Messaging gateway lifecycle |
hermes tools | Enable/disable toolsets |
hermes skills browse|install|list | Skill catalog |
hermes cron list|create | Scheduled jobs |
hermes insights | Usage & cost analytics |
/new, /compress, /stop | In-session: fresh session, compress context, kill background work |
Model routing on a budget, memory hygiene, skill curation, profiles, and the config knobs that separate a demo from a daily driver.
Official docs: hermes-agent.nousresearch.com/docs · Source: github.com/NousResearch/hermes-agent