Hermes Agent Complete Setup Guide (2026)

I've been running Hermes Agent daily since v0.16.0 — first on a WSL2 Windows setup, then on a dedicated ARM64 Debian server. It's my primary AI assistant for coding, content research, site maintenance, and server management. This guide walks you through everything I wish I'd known on day one, from installation to the real gotchas that the quickstart docs don't cover.

I tested every step in this guide against Hermes Agent 0.17.0, Python 3.12, and Ubuntu 24.04 (also works on Debian 11/12 and WSL2). The configuration examples use SenseNova's DeepSeek V4 Flash as the primary model — the provider I've found offers the best balance of speed, quality, and cost for self-hosted use.

According to Gartner's 2024 Hype Cycle for AI, AI agents are projected to be adopted by over 40% of enterprises by 2027, up from less than 5% in 2024. The open-source AI agent ecosystem — led by frameworks like Hermes Agent — is driving this shift by making agentic workflows accessible to individual developers and self-hosters alike.

1. Environment Preparation

Recommended specs: 1 CPU core, 2GB RAM, 10GB disk. Ubuntu 24.04 LTS or Debian 12.

# Base dependencies
sudo apt update && sudo apt upgrade -y
sudo apt install python3 python3-pip python3-venv git curl -y

# Verify versions
python3 --version   # needs >= 3.10
curl --version

2. Installing Hermes

Method 1: pip Install (Recommended)

pip install hermes-agent

# Verify installation
hermes --version
# Should output something like: Hermes Agent 0.16.0

Method 2: Install from Source (Development/Bleeding Edge)

git clone https://github.com/fulankizao/hermes-agent-src.git
cd hermes-agent-src
pip install -e .
hermes --version

After installation, running hermes for the first time will automatically create the ~/.hermes/ directory and default configuration file.

3. Configuring Models (Most Critical Step)

Hermes supports 30+ model providers. According to industry analysis, the AI model API market surpassed $7B in 2025, with open-weight and API-accessible models growing at over 60% year-over-year. Here are the three most common configuration methods:

Option A: SenseNova (DeepSeek V4 Flash, Best Value)

# ~/.hermes/.env
SENSENOVA_API_KEY=YourKey

# ~/.hermes/config.yaml
model:
  default: deepseek-v4-flash
  provider: custom

providers:
  custom:
    base_url: https://api.sensenova.cn/v1
    api_key: ${SENSENOVA_API_KEY}
    models:
      deepseek-v4-flash:
        name: deepseek-v4-flash

Option B: Zhipu GLM (Direct Connection in China, No Proxy Needed)

# ~/.hermes/.env
GLM_API_KEY=YourZhipuKey
ZAI_API_KEY=YourZhipuKey

# ~/.hermes/config.yaml
model:
  default: zai/glm-4-flash
  provider: zai

Option C: OpenRouter (Multi-Model Aggregation, for Overseas Use)

# ~/.hermes/.env
OPENROUTER_API_KEY=YourKey

# ~/.hermes/config.yaml
model:
  default: openrouter/deepseek/deepseek-chat
  provider: openrouter

# Add at the top level of config.yaml
fallback_model:
  - provider: zai
    model: glm-4-flash
  - provider: openrouter
    model: openrouter/deepseek/deepseek-chat

4. Verifying Model Availability

# Test if the model works properly
hermes chat -q "Introduce yourself in one sentence"

# If it errors, check:
# 1. Whether the API Key in .env is correct
# 2. Whether the network can reach the API endpoint
# 3. Whether the model name is correct

5. Starting the Web Dashboard

The Dashboard provides a Web interface for managing configuration, viewing sessions, and switching models.

Manual Start

# Run in foreground (for testing)
hermes dashboard --port 9119 --host 127.0.0.1

# Run in background (for production)
nohup hermes dashboard --port 9119 --host 127.0.0.1 --no-open --skip-build \
  > ~/.hermes/dashboard.log 2>&1 &

Visit http://localhost:9119 to see the Dashboard.

systemd Auto-Start

Make the Dashboard start with the system and auto-recover on crash:

sudo tee /etc/systemd/system/hermes-dashboard.service > /dev/null << 'EOF'
[Unit]
Description=Hermes Agent Dashboard
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/hermes dashboard --port 9119 --host 127.0.0.1 --no-open --skip-build
Restart=on-failure
RestartSec=15

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-dashboard

# Verify
curl -s -o /dev/null -w "HTTP %{http_code}" http://127.0.0.1:9119/
# Should output: HTTP 200

6. Connecting QQ Bot

Connect via the QQ Open Platform so Hermes can chat with you on QQ.

6.1 Register a Bot

1. Visit QQ Open Platform, register and create a bot
2. Get AppID and Client Secret
3. Set basic info like callback URL (if required, enter anything — Gateway doesn't rely on callbacks)

6.2 Configure Environment Variables

# Add to ~/.hermes/.env
QQ_APP_ID=YourAppID
QQ_CLIENT_SECRET=YourClientSecret
QQ_ALLOW_ALL_USERS=true

6.3 Start the Gateway

# Start the message gateway
hermes gateway run

On my setup, I noticed the Gateway needs to be started as root — the QQ WebSocket connection requires filesystem access that doesn't work under a non-root user. Also, the connection times out after 30 minutes of inactivity (code 4009), which is normal — Hermes auto-reconnects. Seeing ✓ qqbot connected in the logs means the connection is successful. Go to QQ and send the Bot a message to test.

6.4 Gateway Auto-Start

sudo tee /etc/systemd/system/hermes-gateway.service > /dev/null << 'EOF'
[Unit]
Description=Hermes Agent Gateway
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/hermes gateway run
Restart=on-failure
RestartSec=10
Environment=HOME=/root

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now hermes-gateway

7. Optimization Tips

8. Frequently Asked Questions

Q: hermes --version produces no output

The entry script may be corrupted. Check the file pointed to by which hermes and confirm it contains the main() call. Fix method:

# Create a fix script
mkdir -p ~/.local/bin
cat > ~/.local/bin/hermes << 'SCRIPT'
#!/bin/bash
exec python3 -c "
import sys
from hermes_cli.main import main
sys.exit(main())
" "$@"
SCRIPT
chmod +x ~/.local/bin/hermes

Q: Error "ModuleNotFoundError: no module named 'hermes_cli'"

Hermes is not installed in the current Python environment. Check if you're using the correct Python: which python3 && pip list | grep hermes. If not installed, run pip install hermes-agent in the correct Python environment.

Q: QQ Bot shows "Connected" but can't receive messages

The transport layer is fine (WebSocket connected), but the user authorization layer is blocking messages. Check:

• Whether QQ_ALLOW_ALL_USERS=true is set in .env
• Whether the Gateway logs show Unauthorized user hints
• Restart the Gateway after modifications: sudo systemctl restart hermes-gateway

Q: Gateway keeps restarting ("already running")

An old manual hermes gateway run & process is occupying the port. Find and kill the old process first, then start the systemd version:

kill $(pgrep -f "gateway run")
sudo systemctl restart hermes-gateway

FAQ

Can I run Hermes Agent on a Raspberry Pi?

Yes, Hermes Agent itself is lightweight and runs on ARM64 devices like Raspberry Pi 4/5 with 4GB+ RAM. However, you will need to use an API-based model provider (e.g., SenseNova or OpenRouter) — local LLM inference on a Pi is not practical for most use cases.

Does Hermes support Telegram and Discord bots too?

Yes. In addition to QQ Bot, Hermes Gateway supports Telegram and Discord message channels. The configuration process is similar — you register a bot on each platform and set the corresponding environment variables (TELEGRAM_BOT_TOKEN or DISCORD_BOT_TOKEN).

How do I update Hermes Agent to the latest version?

If installed via pip, run pip install --upgrade hermes-agent. If installed from source, pull the latest code with git pull inside the source directory. After updating, restart the Dashboard and Gateway services with sudo systemctl restart hermes-dashboard hermes-gateway.

What is a "skill" in Hermes Agent?

Skills are plugin modules that extend Hermes's capabilities — similar to plugins in ChatGPT. Skills can browse the web, run shell commands, query databases, or perform scheduled tasks via cron. You can write custom skills in Python and place them in ~/.hermes/skills/. For more details, refer to the official Hermes Agent documentation.

Can I use Hermes Agent without a Web Dashboard?

Absolutely. The CLI command hermes chat is fully functional without the Dashboard. You only need the Dashboard for the web interface and remote management. For a minimal setup, just install Hermes, configure a model, and use the terminal directly.

Next Steps

Once configured, you can:

• Explore the Hermes Skills system — add custom skills to extend functionality
• Connect more messaging platforms (Telegram, Discord)
• Write your own Agent workflows
• Configure cron scheduled tasks — let the Agent perform operations periodically

Related Articles

• WSL2 Production Environment Complete Setup — Useful if you're deploying Hermes on WSL
• Linux Server Disk Cleanup: Complete Guide — Remember to clean logs if Hermes runs for a long time
• FastAPI Project: From Development to Deployment — Another self-hosted service deployment approach