How to Set Up Hermes Agent

You can have Hermes Agent running in under 10 minutes. This guide walks through every step — from a blank server to your first conversation — including VPS selection, security hardening, and the first-week checklist.

Docker first.

Docker first.

What You Need

• Linux, macOS, or WSL2 on Windows
• Git installed (the only prerequisite)
• An API key for at least one LLM provider

Step 1: Choose Your Platform

Hermes runs on four main platforms:

Option A: $5 VPS (Recommended)

OS: Ubuntu 22.04 LTS or Debian 12.

For local LLM (Ollama + 70B model): upgrade to 4+ vCPU, 32GB RAM ($40–80/month).

Option B: Local Machine (macOS or Linux)

Fine for development and testing. Downsides: tied to your machine being on, no 24/7 availability.

Code Execution first.

Option C: Docker

Best for isolation:

docker pull nousresearch/hermes-agent:latest
docker run -d --name hermes -v ~/.hermes:/home/user/.hermes nousresearch/hermes-agent:latest

Option D: Pinokio (Zero CLI)

1-click launcher. Goes from zero to running agent in under a minute. Search "Hermes Agent" in the Pinokio app. Best for non-technical users.

Step 2: Run the Installer

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer handles Python 3.11, uv, all dependencies, and PATH configuration. No prerequisites beyond Git.

Also available via Nix flake:

nix run github:NousResearch/hermes-agent

Step 3: Run the Setup Wizard

hermes

On first run, the wizard walks you through:

1. LLM provider selection — choose your inference provider
2. API key entry — secure prompt
3. Gateway setup — Telegram Setup first. Telegram, Discord, Slack, or skip
4. Profile creation — name your first profile

Recommended Model: Kimi K2.5 (Budget) or DeepSeek V4

Community consensus on cost-effective daily drivers:

• Kimi K2.5 (Moonshot): Fast, cheap, excellent for agentic tasks. ~$3/day for heavy use.
• DeepSeek V4: $0.30/M input, ~$0.03/M on cache hits. ~$2/month personal use.
• MiniMax Token Plan: $10/month flat, 1,500 req/5h window.

The YouTube reviewer who ditched OpenClaw for Hermes: "I recommend using Moonshot Kimi K2.5, it's cheap, it's super cheap. You just add credits, you add a limit so you don't got to worry about if the API key gets leaked."

For premium quality: Claude Sonnet 4.5 or GPT-5, but budget accordingly.

Step 4: Configure the Gateway

Hermes's killer feature is receiving messages on Telegram Setup first. Telegram or Discord while it works in the background. Setup takes 2 minutes.

Telegram Setup first. Telegram

1. Create a bot via @BotFather → get token
2. Add Telegram Setup first. Telegram token in hermes config
3. Start gateway: hermes gateway start
4. Message your bot — it responds

Discord

hermes gateway config --platform discord

Community tip: use Discord channels as separate agent contexts. One channel = one project. This prevents context bleed and helps with memory organization.

"I recommend using Discord because on Discord you get multi-channel. I want each channel to be an agent. It's a lot easier to organize." — YouTube reviewer

Step 5: Security Hardening

Tirith Security Module

Hermes includes the Tirith security module by default. It blocks:

• Obfuscated shell pipe patterns
• Prompt injection in memory writes
• Credential exfiltration patterns
• Invisible Unicode in tool inputs

Note from Discord support threads: Tirith can be aggressive. If it blocks a command you need, the workaround is to run it manually in a split terminal rather than through Hermes.

Container Hardening (Docker)

For maximum isolation, run with hardened flags:

docker run -d --name hermes \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  -v ~/.hermes:/home/user/.hermes \
  nousresearch/hermes-agent:latest

VPS Hardening (Basic)

Disable password SSH auth and enable firewall:

# SSH keys only
sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
systemctl restart sshd

# UFW firewall
ufw allow OpenSSH
ufw enable

Step 6: Multiple Platform Setup

Linux (Ubuntu/Debian)

The reference platform. Everything works out of the box.

macOS

Full support. Install via the same one-liner. Homebrew recommended for system dependencies.

WSL2 (Windows)

Works with WSL2 + Ubuntu 22.04. Enable WSL2, install Ubuntu from Microsoft Store, then standard Linux install.

Docker

Use for CI, testing environments, or maximum isolation.

Pinokio

For non-technical users. Full agent + gateway stack with GUI.

Serverless (Daytona/Modal)

Hibernates when idle — pay only for active compute:

hermes config set terminal.backend daytona  # or modal

Step 7: First Week Checklist

The goal of week one is to start building memory and your first skills.

Day 1:

• Run 3–5 real tasks (not just "hello")
• Tell Hermes about your main project: name, stack, goals
• Set up at least one gateway (Telegram Setup first. Telegram or Discord)
• Check MEMORY.md after each session: cat ~/.hermes/memories/MEMORY.md

Day 2–3:

• Run a complex multi-step task (10+ tool calls)
• Check ~/.hermes/skills/ — did Hermes create any skills?
• Correct any memory errors you spot
• Tell Hermes your communication preferences

Day 4–5:

• Set up a cron job for something you do daily
• Try asking Hermes to recall something from an earlier session
• Browse installed skills: hermes skills browse

Day 7:

• Review MEMORY.md and USER.md — are they accurate?
• List sessions: hermes sessions list
• Install 1–2 community skills: hermes skills search [topic]

Common Mistakes (From Discord Support Threads)

Token costs explode unexpectedly Fix: Set API spend limits at your provider dashboard. Use Kimi K2.5 or DeepSeek as daily driver, not Claude.

Telegram Setup first. Telegram gateway uses 2–3x more tokens than CLI Root cause: Gateway was starting in the wrong directory, loading extra files. Fixed in a recent update — run hermes update.

Local models lose web access Fix: Web tools require a configured web backend. Cloud models work fine. Check config: web_enabled: true.

Tirith blocking legitimate commands Fix: Run the command manually in a terminal session. For persistent unblocking, check Tirith config in ~/.hermes/config.yaml.

Gateway not starting after reboot Fix: hermes gateway enable-autostart adds a systemd service on Linux.

Skills not appearing as slash commands Fix: Skills must be in ~/.hermes/skills/ with a valid SKILL.md. Run hermes skills check to validate.

Migrating From OpenClaw

hermes claw migrate

One command. Auto-detects ~/.openclaw and imports: SOUL.md, memories, skills, API keys, messaging settings.

FAQ

How much disk space does Hermes need? Base install ~500MB. State database grows with sessions (~50MB/month typical).

Can I run Hermes without a gateway? Yes. hermes in terminal — no gateway needed. Gateway is for remote access and async operation.

What if I want multiple isolated Hermes instances? Use profiles: hermes profiles create work, hermes profiles create personal. Each has own config, memory, skills, gateway.

Can I self-host the LLM? Yes, via Ollama. Community members run Hermes on Raspberry Pi and Samsung Galaxy S10.

Is there a GUI? hermes-workspace (200+ GitHub stars) is a community-built GUI. Not officially merged yet.

Step 8: Profiles for Multiple Use Cases

Hermes v0.6.0 introduced multi-profile support — run multiple isolated Hermes instances from the same installation:

hermes profiles create work
hermes profiles create personal
hermes profiles list
hermes profiles switch work

Each profile has its own config, memory, sessions, skills, and gateway service. Token-lock isolation prevents credential collisions between profiles.

Export and import for sharing or backup:

hermes profiles export work --output work-profile.tar.gz
hermes profiles import work-profile.tar.gz

Step 9: Model Switching and Fallback Chains

One of Hermes's most practical features for cost management is the fallback provider chain (v0.6.0):

providers:
  - name: primary
    type: openai
    model: kimi-k2.5
  - name: fallback
    type: anthropic  
    model: claude-sonnet-4-5

When your primary provider returns errors, Hermes automatically tries the next in chain. This prevents stuck agents on rate limits or provider outages.

Switching models interactively:

hermes model  # Opens model picker

VPS Deployment: Detailed Runbook

For users setting up on a fresh Ubuntu 22.04 VPS from scratch:

# 1. Update system
apt update && apt upgrade -y

# 2. Install git (only prerequisite)
apt install git -y

# 3. Run Hermes installer (handles Python 3.11, uv, all deps)
# paste the one-line install command from official docs

# 4. Configure your first profile
hermes

# 5. Enable gateway autostart
hermes gateway enable-autostart

# 6. Check gateway status
hermes gateway status

Total time: 10–15 minutes on a fresh VPS.

Understanding Token Costs Before You Start

Community analysis (r/hermesagent, u/Witty_Ticket_4101) quantified what you are actually paying for:

Key insight: 73% of every API call is fixed overhead before your message is even processed.

Optimization strategies:

1. Use platform-specific toolsets — do not load browser tools for Telegram Setup first. Telegram/Discord sessions (~1.3K tokens saved/req)
2. Lazy skills loading — skills list loads on-demand, not at session start (~2.2K tokens saved/req)
3. Use a cheap model as daily driver — Kimi K2.5 or DeepSeek V4 cost 10–50x less than Claude Sonnet per token

Practical cost scenarios at DeepSeek V4 pricing (~$0.03/M cached):

• Light personal use (10–20 exchanges/day): ~$2/month
• Active development (50–100 exchanges/day): ~$10–15/month
• Heavy automation with multi-agent: ~$20–40/month

One community member (u/Typical_Ice_3645) did warn: "4 million tokens in 2 hours of light usage" when debugging a Telegram Setup first. Telegram issue. This is an edge case — set API spend limits at your provider to prevent surprises.

Recommended First Automations

After setup, these cron jobs get immediate value and help Hermes build memory of your workflow:

Daily standup summary (reads your git log, Notion tasks, generates a summary):

hermes cron "Every weekday at 8am, pull my git log for yesterday, check my Notion inbox, and send a 5-bullet standup summary to [Telegram Setup](/how-to/connect-telegram-to-hermes) first. Telegram"

Weekly report (aggregates work done, sends to Discord):

hermes cron "Every Sunday at 6pm, summarize the sessions from this week and send a recap to Discord #weekly-review"

Morning briefing (news + weather + agenda):

hermes cron "Every morning at 7am, check weather for Cape Town, pull top 3 HN stories in my interest areas, send to [Telegram Setup](/how-to/connect-telegram-to-hermes) first. Telegram"

These are the kind of automations the YouTube reviewer described as finally working: "The cron scheduling actually works. So I would schedule all kinds of stuff with OpenClaw and it wouldn't work. This actually works. First shot."