Hermes Agent Setup Guide: Run NousResearch's Agent 24/7 on Telegram

Hermes Agent is NousResearch's open-source AI agent, and it has quickly become one of the most interesting agents you can actually run yourself. This guide covers a complete Hermes Agent install on your own Linux VM — the same steps a production deployment uses — plus configuration, Telegram pairing, and the managed alternative if you'd rather skip the terminal.

What Is Hermes Agent?

Where most chatbots reset with every conversation, Hermes Agent is built to accumulate capability over time:

• Skills — reusable task definitions the agent learns and repeats reliably
• Persistent memory — context about you, your projects, and past work survives across sessions
• CLI workflows — the agent can run command-line tasks on its own machine
• Scheduled jobs — recurring work like daily summaries or cron-style automations
• MCP integrations — connect external tools through the Model Context Protocol
• Messaging gateway — talk to it over Telegram, Discord, Slack, WhatsApp, Signal, SMS, email, and more

In practice that combination changes how you use an agent. You can teach Hermes a skill once — "every morning, pull my calendar, summarize my unread email, and message me a briefing" — and it becomes a scheduled job that just happens. Ask it to track a project and the context is still there next week. Wire in an MCP server for your task tracker or database and those tools become part of its vocabulary.

If you're weighing it against OpenClaw, read OpenClaw vs Hermes Agent — short version: OpenClaw is the stronger everyday personal assistant, while Hermes shines for skill-heavy, long-running workflows. Many people end up running both.

Prerequisites

• A Linux VM (Ubuntu LTS or Debian) with 2 vCPU / 4 GB RAM and systemd
• git and curl installed
• uv — the Python package manager from Astral; it also installs Python 3.11 for you, so no system Python wrangling
• A free Telegram bot token from @BotFather
• An LLM API key from Google, Anthropic, or OpenAI

Step 1: Create a User and Clone the Release

Run the agent under its own system user, never as root. Then clone the repository and check out the latest release tag (currently v2026.7.20):

useradd -m -s /bin/bash hermes
git clone https://github.com/NousResearch/hermes-agent.git /opt/hermes-agent
cd /opt/hermes-agent
git fetch --depth=1 origin tag v2026.7.20
git checkout v2026.7.20
chown -R hermes:hermes /opt/hermes-agent

Step 2: Install uv, Python 3.11, and Dependencies

As the hermes user, install uv, let it provision Python 3.11, create a virtual environment, and sync the project with all extras:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.11
cd /opt/hermes-agent
uv venv venv --python 3.11
uv sync --all-extras --locked

If the lockfile sync ever fails on your platform, uv pip install -e ".[all]" into the same venv is the fallback. Optionally symlink the CLI so it's on your PATH (ln -s /opt/hermes-agent/venv/bin/hermes ~/.local/bin/hermes), then run hermes doctor to sanity-check the install.

Step 3: Run It as a systemd Service

The gateway must survive crashes and reboots, so give it a service unit at /etc/systemd/system/hermes.service:

[Unit]
Description=Hermes Agent Gateway
After=network.target

[Service]
Type=simple
User=hermes
WorkingDirectory=/opt/hermes-agent
EnvironmentFile=-/etc/hermes/user.env
ExecStart=/opt/hermes-agent/venv/bin/hermes gateway
Restart=always

[Install]
WantedBy=multi-user.target

Enable it with systemctl daemon-reload && systemctl enable --now hermes, then confirm it's healthy with systemctl is-active hermes and journalctl -u hermes.

Step 4: Configuration

Hermes reads secrets from an environment file (/etc/hermes/user.env, mirrored to ~/.hermes/.env) — keep it chmod 600:

TELEGRAM_BOT_TOKEN=123456:ABC...   # from @BotFather
TELEGRAM_ALLOWED_USERS=your_username
GATEWAY_ALLOW_ALL_USERS=false
GOOGLE_API_KEY=...   # or ANTHROPIC_API_KEY / OPENAI_API_KEY

Model and provider selection lives in ~/.hermes/config.yaml. Point it at whichever model your API key unlocks — current well-supported options include:

• Google — google/gemini-2.5-flash (a great fast default), google/gemini-3-flash, or google/gemini-3.1-pro for harder tasks
• Anthropic — anthropic/claude-sonnet-4-6 for strong reasoning, anthropic/claude-opus-4-6 for maximum capability
• OpenAI — openai/gpt-5.2, or openai/gpt-5.2-instant when speed matters most

Keep GATEWAY_ALLOW_ALL_USERS=false. Your bot is reachable by anyone who finds its username; the allowlist plus pairing is what keeps strangers from spending your API credits.

Step 5: Pair Your Telegram Account

With the service running, open your bot in Telegram and send /start. Hermes responds with a pairing code; approve it and your account is linked. From that point the agent answers you — and only you — 24/7, with its memory and skills accumulating from the first conversation.

What to try first

Good opening moves that exercise the parts that make Hermes different:

• "Every weekday at 8am, send me a summary of my calendar and anything urgent." — creates a scheduled job
• "Learn this as a skill: when I say 'ship report', collect this week's commits and draft a status update." — teaches a reusable skill
• "Remember that the staging server lives at 10.0.0.4 and deploys happen from the release branch." — seeds persistent memory you can rely on weeks later

Troubleshooting the Install

The failure modes are predictable, so here's the short list:

• uv: command not found — the installer puts uv in ~/.local/bin, which may not be on PATH in a fresh shell. Call it by full path or re-source your profile.
• uv sync fails on the lockfile — fall back to uv pip install -e ".[all]" inside the venv; it installs the same project with resolved-at-install versions.
• Service runs but the bot never replies — almost always the environment file: a mistyped TELEGRAM_BOT_TOKEN, or your username missing from TELEGRAM_ALLOWED_USERS. Fix the file and systemctl restart hermes.
• systemctl is-active hermes says failed — read journalctl -u hermes -n 80. Missing API key variables and a broken venv path are the two usual suspects, and both show up plainly in the log.

Keeping It Updated

Hermes Agent releases move quickly, and updating a manual install is the same dance every time: fetch the new release tag in /opt/hermes-agent, check it out, re-run uv sync --all-extras, and restart the service. Budget a few minutes per release — more when a release changes configuration format and you need to read the changelog first. It's not hard work, but it never stops arriving, and skipping updates means missing new skills and fixes.

The Hosted Alternative: Hermes on Claw Deployer

Everything above is exactly what Claw Deployer automates. Choose Hermes Agent in the deploy form and it provisions a dedicated Hetzner VM, checks out the latest release tag, builds the uv environment, writes the systemd unit and locked-down env files, starts the gateway, and hands you the pairing step — in under a minute instead of an afternoon. Release updates and service recovery are handled from then on.

You can also run Hermes alongside OpenClaw on the same server: each agent gets its own system user, directory, environment file, and systemd service, with its own Telegram bot token. It's a clean way to use OpenClaw as your daily assistant while Hermes handles scheduled, skill-based work. The deployment walkthrough shows the full dashboard flow, and plans start at $29/mo.