.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
This is the hub page for everything we've written about Hermes Agent, the open-source self-hosted AI agent that Nous Research shipped in February 2026. If you've been bouncing between tabs trying to figure out where to start, this guide walks the whole arc in the order most people end up taking:
Decide if Hermes is the right pick. Install it. Migrate your old setup if relevant. Wire up a messaging channel. Harden the box for production. Learn the memory model so you can debug the agent. Recover when something inevitably breaks.
Read it top to bottom on a first pass, then bookmark the sections you need to come back to. Every numbered topic links out to a longer tutorial covering it in detail. The library grew faster than we expected over the past few months, so by the time you reach the end you'll see the agent is more configurable than the first install impression suggests.
Ready? Let's go!
1. Decide if Hermes is the right agent for you
Hermes is one of the popular self-hosted agents we host on LumaDock. They're not interchangeable. The choice depends on how much polish you want, how much control you need over memory and how comfortable you are with a fast release cadence.
Start with the analytical comparison in Hermes Agent vs OpenClaw for self-hosting. It walks the operational trade-offs honestly. OpenClaw has a bigger skill library and a longer track record on every messaging platform. Hermes has a cleaner memory model, an explicit learning loop and a faster release pace. Neither one is uniformly better.
If you're already running OpenClaw and just want to know if a switch is worth your weekend, the decision framework in when to migrate from OpenClaw to Hermes Agent covers the four most common reasons people make the jump and the two reasons to stay put.
If your use case is more "I want a simple, predictable bot that doesn't try to learn behaviours on its own", ZeroClaw is worth a look before either of the heavier options. The ZeroClaw vs OpenClaw comparison sketches where the lightweight option wins. If you decide to go that route, our ZeroClaw VPS setup guide picks up from there.
For the broader OpenClaw library (templates, channels, security writeups, cost guides), the OpenClaw complete guide is the equivalent of this article on the OpenClaw side.
2. Get Hermes installed
Once you've picked Hermes, the next decision is install path. The install Hermes Agent on Ubuntu 24.04 walkthrough covers the 90-second curl-pipe-bash flow plus the manual fallback for the few edge cases where the official installer chokes. Read the first half if you just want the agent on the box. Read the second half if your environment has anything unusual about it: locked-down ports, non-standard Python, air-gapped servers.
Windows users have a separate decision to make because Hermes doesn't run natively on Windows. The Hermes Agent on Windows: WSL2 vs Desktop guide compares the two supported paths so you don't waste an evening fighting the install script in PowerShell (it won't work; the error message only tells you why on the second attempt).
Two issues catch nearly everyone within the first hour of install. The shell can't find the binary you just installed: covered in fix the hermes command not found error, which is almost always a PATH reload problem. The first chat attempt errors with "no inference provider configured": fixed in fix the no inference provider configured error with three commands. Don't bother debugging those from scratch, the patterns are the same on every machine.
If you intend to run Hermes against a local model through Ollama, there's a foot-gun specific to that path. Ollama's default context window is too small for what Hermes pushes per turn. The symptoms (the model "forgetting" mid-session, weird short replies) look like a model problem when really it's a config problem. The Ollama context window fix covers num_ctx in 5 minutes.
If you'd rather skip the install entirely, the LumaDock Hermes Agent template ships with the agent pre-installed on Ubuntu 24.04, dashboard ready to pair over SSH and the hermes CLI on the PATH. The Hermes Agent VPS setup guide in our knowledge base walks the first-boot menu screen by screen.
3. Migrate from OpenClaw
If you're starting from scratch, skip this section. If your previous agent was OpenClaw, the canonical walkthrough is how to migrate from OpenClaw to Hermes Agent. It covers the hermes claw migrate command end to end including the pre-flight checks and the post-migration verification.
The migration is rarely a perfectly clean run. When it isn't, our fix Hermes claw migrate failures and silent skips article catalogues the eight failure modes we've seen most often. Silent skill skips. Persona conflicts. Dirty workspaces. Missing API keys. Schema mismatches. Partial state.db transfers. Broken symlinks. The friendly-but-confusing dry-run output.
For people who'd rather not commit to a switch immediately, our run OpenClaw and Hermes Agent on the same VPS guide walks the coexistence pattern. Separate users, separate ports, separate systemd units, no shared state. You get to trial Hermes for a few weeks with your old agent still answering on the channels it owned.
4. Pick a messaging channel
Hermes only becomes useful once it's reachable from somewhere you read messages. The most common channels each get a dedicated tutorial.
Hermes Agent Telegram bot setup and reliability is the one most people start with. Telegram is the cheapest channel to get right: free BotFather, polling out of the box, no inbound port exposure. The article covers the allowlist pattern that keeps strangers from running up your token bill. If the gateway log shows "token was rejected" after restart, the Telegram bot token rejected fix covers the four config locations Hermes might be reading from (most cases are wrong-file edits, not wrong tokens).
For Discord servers, Slack workspaces and yes Telegram in parallel, our multi-platform messaging gateway for Hermes Agent walks the multi-channel setup with shared memory and identity mapping. This is the "one brain, many faces" article.
WhatsApp is the polarising one IMO. The Baileys-based bridge works but it's a third-party reverse-engineered library and accounts do get banned. Our Hermes Agent WhatsApp setup with Baileys tutorial covers the dedicated-number pattern that minimises ban risk plus the voice-note transcription flow people love. Two WhatsApp-specific bugs show up often enough to have their own fixes. The WhatsApp bridge localhost:3000 connect error hits when the Node bridge process isn't running or has crashed. The WhatsApp bridge dependencies install stuck walkthrough explains why setup stalls on low-memory VPSes (it's npm getting OOM-killed silently) and the swap trick that solves it.
For overnight email triage and background tasks, Hermes Agent email gateway with IMAP and SMTP shows the Gmail app-password setup, the inbox-filter pattern that keeps Hermes from answering marketing emails and the outbound-only configuration people use for transactional notifications.
5. Make it production-grade
Once Hermes is on a channel, it needs to stay up. The operational baseline starts with three articles.
The simplest path is run Hermes Agent 24/7 with systemd. A unit file, a restart policy and a journald log rotation get you to "the agent recovers from crashes by itself" in about fifteen minutes. The article includes a hardened unit (NoNewPrivileges, ProtectSystem, ProtectHome) for people who want defence in depth without reaching for containers.
If you prefer containers, Hermes Agent on Docker Compose with persistent state covers a production-ready Compose file with healthchecks, named volumes for state.db and skills plus a watchtower service for auto-updates. The persistent-state section is the one most people get wrong on the first try.
For anything exposed to the public internet (the web dashboard, a webhook receiver, the community WebUI), the Hermes Agent behind Nginx with HTTPS and basic auth guide is what you want. Let's Encrypt, basic auth, WebSocket passthrough and a sensible default location block.
Two more articles round out the production set. The Hermes Agent production hardening checklist is a 15-item walkthrough covering non-root operation, command-approval mode, sandboxing of shell tools, secrets management with sops or systemd-creds and the audit log everyone forgets to enable. The Hermes Agent backups for state.db, skills and identity article covers the SQLite-aware backup script, GPG encryption at rest, the systemd timer schedule that runs it nightly and how to restore on a different host without breaking your memory.
Past those five, three operational concerns come up enough to deserve their own articles. The Hermes Docker sandbox and SSRF protection setup covers the two security defences worth enabling before you really need them (sandboxed shell execution, blocked private-network browse calls). The Hermes gateway memory leak OOM fix covers a known upstream leak that bites every long-running VPS deployment somewhere between 20 and 36 hours of uptime. The mitigation is a scheduled restart timer, not glamorous but reliable. The Hermes token spend tracking and budget alerts guide covers the moment a few weeks in when you realise the agent has been quietly racking up a bigger bill than you expected.
6. Understand and edit the brain
Hermes is more debuggable than most agents because its memory is flat files plus one SQLite database. You can read it with a text editor and grep it with normal tools. The Hermes Agent memory: SOUL.md, MEMORY.md and state.db article maps the three layers (persona, user facts, session state) and shows the hand-editing patterns we use to fix common memory bugs without nuking the agent's history.
The split between files matters more than you'd expect on day one! SOUL.md, AGENTS.md, USER.md and MEMORY.md explained covers what belongs in each and why dumping everything into SOUL.md creates the agent equivalent of a junior dev who tries to follow seven contradictory style guides at once.
If your built-in markdown memory grows past a few hundred kilobytes and you want semantic retrieval instead of loading the whole file every prompt, the Hermes memory stack with Honcho and pgvector piece covers the two paths most people pick (hosted Honcho or self-hosted Postgres with the vector extension).
Skills are the other half of the brain. The agent writes its own skill files as it learns, and the edit Hermes Agent skills without breaking the loop tutorial covers the user_locked: true frontmatter that protects your hand-edited skills from being overwritten, the fork pattern for adapting community skills and the git-based workflow for sharing skills across boxes.
Cost is the third concern most people raise after a week of use. Cut your Hermes Agent token bill in half breaks down the issue #4379 overhead numbers (the ~13.9K tokens of fixed context per call), the four provider-routing tricks that move spend from Anthropic to cheaper open-weight models for the right kinds of tasks, the /compress command for long conversations and when self-hosting an open-weight model on a GPU box pays for itself.
7. Manage providers, cost and rate limits
Hermes is provider-agnostic but the moment you wire up real traffic, the provider becomes the single most important moving part. Three error codes dominate the support tickets we see: 401, 402 and 429. Each has its own remediation and conflating them is what wastes weekends :)
Fix Hermes Agent 401 authentication errors handles the auth failures across Anthropic, OpenRouter, MiniMax and the rest. Nine times out of ten the key itself is fine and Hermes is loading the wrong one from auth.json or a stale env var. The article walks the curl-based verification flow that isolates the real cause in under five minutes.
Fix Hermes 402 quota errors with fallback providers is the right read when your gateway suddenly goes silent at midnight because the primary provider ran out of credits. Older Hermes versions treated 402 as fatal and killed the gateway; newer ones retry and surface a clean error. The article covers both the upgrade and the fallback-provider pattern that keeps a production bot alive when the primary is exhausted.
Hermes Agent 429 rate limit errors and tracebacks covers the per-provider rate-limit quirks. Anthropic and OpenAI report differently. MiniMax and GLM sometimes lie about it (they return 401 for what is really a rate limit). The article walks Hermes's built-in retry behaviour, the agent-side throttle config and the four-line cron alert that catches a spike before users do.
If 429s become a recurring theme, the Hermes Agent credential pools for multi-key setup piece covers the official feature that nobody talks about. Two keys on the same provider rotated round-robin gives you twice the per-account rate budget at zero extra hourly cost. It pairs well with fallback providers, since pools handle per-account limits and fallbacks handle full provider outages.
On the visibility side, our track Hermes Agent token spend and set budget alerts guide covers what the built-in hermes usage command shows you, the community dashboards that bolt on top and the alert patterns that fire before the credit card statement does.
8. Reach the agent remotely
Most setups start with the dashboard on localhost and Hermes Desktop (or just the browser) on the same machine. That works for personal use. The moment you want messaging gateways running 24/7 or you want to switch between laptops without losing context, the agent moves to a VPS and the question becomes how to reach it cleanly from wherever you are.
The community WebUI is the lightest option. Hermes WebUI for remote access to your agent covers the install, the OIDC authentication setup so it isn't open to the public internet, and the Nginx configuration that puts it behind the same reverse proxy as everything else on your VPS.
If you want a native-feeling desktop app, the Hermes Desktop remote backend on a VPS tutorial walks the pairing flow (Desktop in remote mode pointed at a VPS-hosted dashboard) plus the WebSocket auth quirks that bite people when they put Cloudflare Access in front. This is the setup I run on my main machine.
For the homelab crowd who'd rather avoid public reverse proxies entirely, access Hermes Agent remotely with Tailscale covers the pattern most r/selfhosted regulars land on eventually. The VPS and the laptop join the same private mesh. Nothing public, no port forwarding, no certbot.
Two Windows-specific issues catch people in this section. Hermes Desktop GPU crash on Windows with NVIDIA is a one-env-var fix for the blank-window or flashing-display bug that hits certain driver combinations. Hermes WSL2 gateway disconnecting on Windows covers the lifecycle problem that kills any long-running service inside WSL2 when you close the last terminal. Three real workarounds, none of them satisfying enough to fully replace running the agent on a real Linux box.
9. Recover when things break
Things break. The agent decides to refuse a tool call you swear it should accept. The database refuses to open. A messaging gateway goes silent for no obvious reason. These articles are the ones you'll bookmark and forget about until you need them.
The most common operational failure in Hermes is the SQLite locking pattern documented in issue #3139. Our fix the SQLite database is locked error in Hermes walkthrough covers the WAL-mode tuning that prevents most of these locks, the busy_timeout and mmap_size settings worth changing, the recovery steps when a lock has wedged a session and the diagnostic commands that tell you if session_search has been silently disabled.
A different failure mode is genuine state.db corruption (usually from hard kills, OOM events or two Hermes processes writing concurrently). The fix Hermes state.db corruption and permission errors piece covers the SQLite .recover flow, the hermes memory repair wrapper around it and the boring habits (clean shutdowns, nightly backups, single-writer discipline) that prevent the next one.
The most confusing failure isn't a database error at all. It's the one where Hermes replies coherently but never runs the tool you asked for. Looks like the agent is broken; usually one of six specific config issues. Hermes Agent talks but doesn't run tools walks the diagnostic in the order I work through it on real installs.
10. Beyond the basics: scheduling, voice, subagents and MCP
These are the features people stumble onto a few months in and discover they're more useful than the docs make them sound. Each one is optional. None of them are required for a working Hermes setup. Together they're what turns the agent from "a smart chatbot on my VPS" into something closer to an assistant.
Schedule recurring tasks with Hermes Agent cron covers built-in scheduling so the agent runs prompts on a timer without system cron or shell scripts. The morning briefing pattern (summarise overnight email at 7 a.m., land in Telegram) is the one that paid back its setup time within a week for me.
Hermes Agent voice mode with faster-whisper and Edge TTS walks the free local stack for voice in / voice out. Local Whisper for speech-to-text, free Microsoft Edge TTS for the spoken reply. No hosted speech APIs, no per-minute cost. The audio quality is shockingly good for something that costs nothing.
For complex tasks that decompose into independent pieces, Hermes Agent subagent delegation for parallel tasks covers the pattern where the main agent spawns helper subagents to work on pieces in parallel and then synthesises the combined result. Useful for multi-source research and comparison work. Wasteful for single-thread tasks because each subagent adds token overhead.
For genuine integration depth, add MCP servers to Hermes Agent covers the official Model Context Protocol integration. Filesystem MCP for typed file operations, Git MCP for repository operations, Postgres MCP for read-only database queries. Once you've configured one, the wider library at modelcontextprotocol/servers opens up (Slack, GitHub, Google Drive, dozens more). This is where Hermes stops feeling like a chatbot and starts feeling like an actual operations tool.
Where the LumaDock template fits in
Everything above works on any VPS. If you don't already have one or you'd rather not deal with the install, the LumaDock Hermes Agent VPS template is the route most readers take. Pick a plan. The server boots with Hermes pre-installed on Ubuntu 24.04. You SSH in. The first-login menu walks you to either the web dashboard or the terminal wizard. You configure your LLM provider and your first channel in a browser. You send the bot a message. The whole loop is under five minutes on a normal connection.
If you're switching from OpenClaw, the same template includes the migration tool. The path is: order the template, tarball your old ~/.openclaw to the new box, run hermes claw migrate, verify, point your channels at the new agent. Our Hermes Agent VPS setup guide in the knowledge base covers the screen-by-screen flow for the first boot.
