How to Set Up Hermes Agent: Complete Installation Guide
Hermes Agent hit 144,000 GitHub stars in three months. The MIT-licensed framework from Nous Research connects any LLM to 20 messaging platforms, runs on six different execution backends, and learns from its own work through a three-layer memory system. This guide walks you through the full setup: prerequisites, the one-line installer, model provider configuration, connecting Telegram and Discord, choosing a terminal backend, and deploying to a VPS as a systemd service. Estimated time: 15-30 minutes for a basic install, under an hour for a production VPS deployment.
Quick Verdict
Hermes has less setup friction than LangGraph, AutoGen, or CrewAI. The only hard prerequisite is git. The one-line installer handles Node.js 18+ and Python 3.10+. The interactive hermes setup wizard configures your model provider, default model, and memory directory in under five minutes. From there, connecting Telegram takes two minutes via BotFather, and Discord takes about five (with one critical gotcha around Message Content Intent). For a persistent deployment, a $5/month VPS plus a systemd service file gets you a 24/7 agent.
Prerequisites Checklist
Click items as you confirm them. State persists in localStorage, so you can close the tab and come back. If any of these are missing, stop and address them before running the installer; the most common broken installs trace back to a skipped prerequisite.
Step 1 – Install the Hermes CLI
Open a terminal and run this. The installer pulls the Hermes CLI, detects missing Node.js or Python versions, and handles them for you:
Check that it worked. If the hermes command is not found, restart your shell or source your profile. The installer adds it to your PATH, but your current session does not pick it up automatically:
After the CLI is on your PATH, run the interactive setup wizard. This walks you through model provider selection, default model configuration, and memory directory setup:
The wizard prompts for four decisions:
- Model provider: OpenRouter is the simplest starting point (single API key, 200+ models, pay-per-token).
- Default model: Pick one with 128K+ context. The wizard suggests options based on your provider.
- Memory directory: Defaults to ~/.hermes/. Honestly, just accept the default here. You will not know whether you want a custom location until you have used the agent for a week.
- Terminal backend: Pick Local. The wizard asks about this too early; the other five options only matter once you have a working agent. We cover them in the Backends section below.
Once that finishes, run hermes doctor. It validates your API key, tests model connectivity, and flags any misconfiguration. Do not skip this. If hermes doctor reports errors, nothing downstream will work. Fix whatever it complains about before moving on.
Agentic AI Compliance Assessment
Compliance checklist for autonomous agent deployments
Download Free →Step 2 – Configure Your Model Provider
You need at least one model provider before the agent can do anything. Hermes works with 24+ providers and 200+ models. The hermes model command manages all of them. Here are the three options most people start with:
Adding a provider
Use the hermes model command to add and manage providers. Here are the three most common configurations:
Run hermes doctor again after adding a provider. You want a clean pass before connecting any messaging platform. Debugging provider issues through a Telegram bot is miserable.
Step 3 – Connect Telegram
If you just want to test Hermes quickly, start here. Telegram has the least friction of any messaging platform: no admin approvals, no workspace setup, no webhooks. Two minutes, start to finish.
- Open Telegram and search for @BotFather.
- Create your bot: Send /newbot to BotFather. Follow the prompts to name your bot. BotFather returns an HTTP API token.
- Set the token in Hermes:
Shell hermes config set telegram.token YOUR_BOT_TOKEN
- Set your allowlist so only you can interact with the bot:
Shell hermes config set telegram.allowlist YOUR_TELEGRAM_USER_ID
- Start the gateway:
Shell hermes gateway start telegram
- Verify: Open Telegram, find your bot, send a message. The bot should respond with full Hermes capabilities using whatever model you configured in Step 2.
Finding your Telegram user ID: Send a message to @userinfobot on Telegram. It replies with your numeric user ID. Use that number in the allowlist. Do not leave the allowlist empty; an open bot accepts messages from anyone.
Step 4 – Connect Discord
Five minutes, but there is a gotcha that will eat an hour if you miss it. Most Discord bot guides skip this step entirely, and it is the single most common reason Hermes appears online but ignores every message.
- Create a Discord application: Go to the Discord Developer Portal, click "New Application," and name it.
- Create a bot: Navigate to the Bot tab in your application, click "Add Bot."
-
Enable Privileged Gateway Intents (CRITICAL): Under the Bot tab, scroll to "Privileged Gateway Intents." Enable both:
- Message Content Intent
- Server Members Intent
"Discord ghosting": the #1 setup failure. Without Message Content Intent enabled, your bot appears online but receives empty message payloads. It literally cannot see what anyone typed. Discord disabled this by default in 2022. If your bot shows as online and never responds, this is almost certainly the cause. Go back to the Developer Portal and toggle it on.
- Generate the invite URL: Go to OAuth2 → URL Generator. Select the bot and applications.commands scopes. Copy the generated URL and open it in your browser to invite the bot to your server.
- Set the token in Hermes:
Shell hermes config set discord.token YOUR_BOT_TOKEN
- Start the gateway:
Shell hermes gateway start discord
- Verify: Mention your bot in a Discord channel. It should respond using Hermes with your configured model.
Other supported platforms
Hermes supports 20 messaging platforms total. Beyond Telegram and Discord, the list includes Slack, WhatsApp, Signal, Matrix, IRC, XMPP, Nostr, Mastodon, Bluesky, WeChat, LINE, KakaoTalk, Viber, Teams, and Google Chat. Each uses the same hermes gateway start
Terminal Backends
When Hermes runs a tool call (creating a file, executing a script, querying an API), it needs somewhere to run that command. That is what the backend controls. Most people never change this from the default (Local), and that is fine. But if you need sandboxing or remote execution, here are your six options:
Step 5 – Deploy to a VPS
A $5/month VPS from Hetzner, DigitalOcean, or Vultr is sufficient for running Hermes with a cloud API provider. This gives you a 24/7 agent that responds on all connected platforms without keeping your laptop open.
- Provision a VPS running Ubuntu 22.04+ or Debian 12+. Minimum 1 GB RAM (2 GB recommended). Other Linux distributions work too; adjust package manager commands accordingly, but Ubuntu has the smoothest install path.
- Install Hermes on the VPS using the same one-line installer from Step 1.
- Configure your provider and gateways as described in Steps 2-4.
- Run gateways as a background daemon:
Shell hermes gateway start telegram --daemon
- Set up a systemd service for automatic restart on reboot:
/etc/systemd/system/hermes.service [Unit] Description=Hermes Agent After=network-online.target Wants=network-online.target [Service] Type=simple User=hermes ExecStart=/usr/local/bin/hermes gateway start telegram --daemon Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target
- Enable and start:
Shell sudo systemctl enable hermes sudo systemctl start hermes sudo systemctl status hermes
Send a message to your bot from your phone. If it responds, the VPS deployment is live. If it does not, check journalctl -u hermes -f for logs. The answer is almost always a bad API key or a misconfigured gateway token.
Memory and Skills Overview
Hermes keeps three kinds of memory, all under ~/.hermes/. The important one to know about first is episodic memory: a SQLite FTS5 database at ~/.hermes/state.db that indexes every conversation with full-text search. This is what lets the agent recall what you talked about three days ago.
The other two layers are more subtle:
- Semantic memory lives in MEMORY.md and USER.md files. These store persistent facts about you and your projects (preferences, project names, environment details) and update automatically over time.
- Procedural memory is the skills system. After 5+ tool calls following the same pattern, Hermes auto-generates a reusable skill and saves it to ~/.hermes/skills/.
Skills
Skills are reusable automation patterns. After Hermes detects a recurring workflow (5+ tool calls following the same pattern), it auto-generates a skill and saves it to ~/.hermes/skills/. Skills become slash commands automatically.
You can also install community skills:
Review before you install. Community skills are code that runs in your agent's context with access to your configured tools and credentials. Read the source, pin versions, and start with the auto-generated skills before pulling from external sources.
For a deep dive into skills, memory architecture, and the self-improving execution loop, see What Is Hermes Agent?
Troubleshooting
Six issues that catch most people on the first install. Click any question to expand.
The installer adds hermes to your PATH, but your current shell session does not know about it yet. Restart your terminal or run source ~/.bashrc (or source ~/.zshrc on macOS).
If the command is still not found after sourcing, check which hermes and verify the install directory is in your PATH.
Your default model has less than the 64K minimum context Hermes requires. Switch to a model with 128K+ context:
hermes model set default
OpenRouter's model list shows context lengths. Filter for 128K+ and pick one within your budget.
This is the "Message Content Intent" issue described in Step 4. Go to the Discord Developer Portal, open your application, navigate to the Bot tab, scroll to "Privileged Gateway Intents," and enable Message Content Intent.
Without this, Discord sends empty message payloads to your bot. The bot is online and receiving events, but the message body is blank, so Hermes has nothing to respond to.
Usually an invalid or expired API key. Run hermes doctor to validate your configuration. It tests API key validity and model connectivity.
If the key is valid but you are still getting 400s, check that the model name matches the provider's expected format. OpenRouter uses provider/model format; direct providers use their own naming.
Do not run Hermes with sudo. The installer is designed for user-level installation. If you get permission errors, use the --user flag.
If the error is on ~/.hermes/ directory access, check ownership: ls -la ~/.hermes/. If it is owned by root (from a previous sudo run), fix with sudo chown -R $USER ~/.hermes/.
Check the ~/.hermes/ directory permissions. The SQLite database at ~/.hermes/state.db and the Markdown files (MEMORY.md, USER.md) need read/write access for your user.
Also verify that Hermes is using the correct memory directory. If you changed it during hermes setup, the gateway must be restarted to pick up the change.
Video Resources
We are producing video walkthroughs covering the install, memory system, and VPS deployment. Check back here as they go live.
Go Deeper
Resources from across Tech Jacks Solutions
Agent Frameworks Compared
Side-by-side analysis of LangChain, CrewAI, AutoGen, and more
Agent Threat Landscape
Security risks specific to autonomous AI agents
FREEAgentic AI Compliance Assessment
Compliance checklist for autonomous agent deployments
PREMIUMPre-Deployment Safety Gate
27-point checklist before any AI tool goes live
IAPP AIGP Certification
The AI governance certification for privacy professionals