Hermes Setup Skill

Hermes Agent Setup

Automated, non-interactive deployment of Hermes Agent. Mirrors the official hermes setup wizard but driven by a coding agent via shell commands and user prompts.

When to Use

• User wants to install, configure, or deploy Hermes Agent
• User wants to reconfigure or add platforms to an existing installation
• Keywords: "hermes setup", "deploy hermes", "configure hermes", "install hermes"

Quick Reference

| Section | Configures | Key Command | |---------|-----------|-------------| | Install | Binary + deps | curl ... \| bash | | 1. Model | Provider + model | hermes config set model.provider | | 2. Terminal | Command execution env | hermes config set terminal.backend | | 3. Agent | Iterations, compression | hermes config set agent.max_turns | | 4. Platforms | Messaging integrations | Write tokens to ~/.hermes/.env | | 5. Tools | Browser, search, TTS, etc. | Write API keys to ~/.hermes/.env | | 6. MCP | External tool servers | hermes mcp add --url |

Files: ~/.hermes/config.yaml (settings), ~/.hermes/.env (secrets, auto-chmod 0600), ~/.hermes/SOUL.md (personality).

Procedure

All commands via Bash. For remote servers, prefix with ssh . Use AskUserQuestion for credentials and choices.

---

Phase 0: Install

Ask: Where to deploy?

• Local machine (macOS / Linux / WSL2)
• Remote server via SSH (provide host)
• Termux (Android)

OS notes:

• Windows native: NOT supported by bash installer. Use PowerShell: irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
• WSL2: Works like Linux, but systemd must be enabled for gateway persistence (systemd=true in /etc/wsl.conf)
• Termux: Uses .[termux] extra, not .[all]. Requires: pkg install python clang rust make pkg-config libffi openssl git nodejs

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

If hermes --version fails, fallback to manual install:

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
git clone https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent
uv venv venv --python 3.11 -q
VIRTUAL_ENV=venv uv pip install -e ".[all]" -q
echo 'export PATH="$HOME/.hermes/hermes-agent/venv/bin:$HOME/.local/bin:$PATH"' >> ~/.bashrc
# Termux: replace ".[all]" with ".[termux]" and add "-c constraints-termux.txt"

Re-run: Safe. Existing ~/.hermes/.env and config.yaml are preserved. Code updates via git pull.

OpenClaw migration: If ~/.openclaw/ exists, hermes setup will auto-detect and offer to import. Or run hermes claw migrate --dry-run manually.

Verify: hermes --version

Post-install: install recommended system deps:

# Linux (apt)
sudo apt install -y ripgrep ffmpeg
# macOS
brew install ripgrep ffmpeg

Install agent-browser (for browser tools):

cd ~/.hermes/hermes-agent && npm install --prefix tools/agent-browser

Run health check: hermes doctor

---

Section 1: Model & Provider

Ask (single-select): Which inference provider?

| Provider | Config Value | Env Var | Auth | |----------|-------------|---------|------| | OpenRouter | openrouter | OPENROUTER_API_KEY | API key | | GitHub Copilot | copilot | COPILOT_GITHUB_TOKEN | OAuth device code | | Google Gemini | gemini | GOOGLE_API_KEY | API key | | Anthropic | anthropic | ANTHROPIC_API_KEY | API key | | Nous Portal | nous | — | hermes login | | Z.AI / GLM | zai | GLM_API_KEY | API key | | Kimi / Moonshot | kimi-coding | KIMI_API_KEY | API key | | MiniMax | minimax | MINIMAX_API_KEY | API key | | MiniMax China | minimax-cn | MINIMAX_CN_API_KEY | API key | | DeepSeek | deepseek | DEEPSEEK_API_KEY | API key | | Hugging Face | huggingface | HF_TOKEN | API key | | Alibaba / Qwen | alibaba | DASHSCOPE_API_KEY | API key | | Ollama (local) | custom | — | None | | Custom endpoint | custom | OPENAI_API_KEY (optional) | Varies |

For API key providers:

echo "=" >> ~/.hermes/.env
chmod 600 ~/.hermes/.env
hermes config set model.provider 
hermes config set model.default 

Copilot OAuth — gh auth login tokens do NOT work. Must use Copilot-specific flow:

python3 -c "
from hermes_cli.copilot_auth import copilot_device_code_login
token = copilot_device_code_login()
if token: print(f'COPILOT_GITHUB_TOKEN={token}')
" >> ~/.hermes/.env

If import fails, prepend: import sys; sys.path.insert(0, '$HOME/.hermes/hermes-agent') User must open the printed URL and enter the code in browser.

Ollama / Custom:

hermes config set model.provider custom
hermes config set model.base_url http://localhost:11434/v1

Credential pool (optional, for same-provider fallback): hermes auth add --provider to add extra keys. Strategy: hermes config set credential_pool_strategies. round_robin

Free model tip: OpenRouter offers free models like nvidia/nemotron-3-super-120b-a12b:free — good for zero-cost testing.

Ask: Which default model?

---

Section 1.5: Auxiliary Models

Hermes uses lightweight auxiliary models for session search, context compression, vision analysis, and memory management. If left as auto, these require an OpenRouter or Gemini key. Otherwise, explicitly configure them.

Ask: Configure auxiliary models with same provider, or skip (use auto)?

If configuring:

for task in vision web_extract compression session_search approval skills_hub mcp flush_memories; do
  hermes config set auxiliary.${task}.provider 
  hermes config set auxiliary.${task}.model 
done
hermes config set compression.summary_model 
hermes config set compression.summary_provider 

Recommended auxiliary models per provider:

| Main Provider | Auxiliary Model | |--------------|----------------| | Copilot | gemini-3-flash-preview or claude-sonnet-4.6 | | OpenRouter | google/gemini-3-flash-preview | | Gemini | gemini-3-flash-preview | | Anthropic | claude-haiku-4.5 | | Ollama | Same local model |

---

Section 2: Terminal Backend

Ask (single-select): Where should commands execute?

| Backend | Value | Extra Config | |---------|-------|-------------| | Local (default) | local | cwd: "." | | Docker | docker | docker_image, resource limits | | SSH | ssh | ssh_host, ssh_user, ssh_port, ssh_key | | Modal | modal | pip install modal && modal setup | | Daytona | daytona | DAYTONA_API_KEY | | Singularity | singularity | singularity_image (HPC only) |

hermes config set terminal.backend 

Docker extra:

hermes config set terminal.docker_image "nikolaik/python-nodejs:python3.11-nodejs20"
hermes config set terminal.cwd /workspace
hermes config set terminal.container_cpu 1
hermes config set terminal.container_memory 5120
hermes config set terminal.container_persistent true

SSH extra: ask for host, user, port, key path, remote cwd.

---

Section 3: Agent Settings

Apply recommended defaults:

hermes config set agent.max_turns 90
hermes config set display.tool_progress all
hermes config set compression.enabled true
hermes config set compression.threshold 0.50
hermes config set session_reset.mode both
hermes config set session_reset.idle_minutes 1440
hermes config set session_reset.at_hour 4

---

Section 4: Messaging Platforms

Ask (multi-select): Which platforms to connect?

Telegram

Guide: "@BotFather → /newbot → copy token. User ID from @userinfobot." Ask: Bot token, user ID, use as home channel?

echo "TELEGRAM_BOT_TOKEN=" >> ~/.hermes/.env
echo "TELEGRAM_ALLOWED_USERS=" >> ~/.hermes/.env
echo "TELEGRAM_HOME_CHANNEL=" >> ~/.hermes/.env

Discord

Guide: "https://discord.com/developers/applications → New App → Bot." Critical: Enable Message Content Intent under Bot → Privileged Gateway Intents. OAuth2 → URL Generator: enable bot + applications.commands scopes. Permissions: Send Messages, Read Message History, Attach Files. Ask: Bot token, allowed user IDs (Developer Mode → right-click → Copy ID), home channel ID

echo "DISCORD_BOT_TOKEN=" >> ~/.hermes/.env
echo "DISCORD_ALLOWED_USERS=" >> ~/.hermes/.env
echo "DISCORD_HOME_CHANNEL=" >> ~/.hermes/.env

Slack

Guide: "https://api.slack.com/apps → New App. Enable Socket Mode → create App-Level Token (connections:write)." Required scopes: chat:write, app_mentions:read, channels:history, channels:read, im:history, im:read, im:write, users:read, files:write. Optional: groups:history (private channels). Events: message.im, message.channels, app_mention. Optional: message.groups. Warning: Without message.channels event, bot works in DMs only. Install to workspace, then /invite @BotName in channels. Ask: Bot Token (xoxb-), App Token (xapp-), allowed user IDs, home channel ID

echo "SLACK_BOT_TOKEN=" >> ~/.hermes/.env
echo "SLACK_APP_TOKEN=" >> ~/.hermes/.env
echo "SLACK_ALLOWED_USERS=" >> ~/.hermes/.env
echo "SLACK_HOME_CHANNEL=" >> ~/.hermes/.env

Matrix

Guide: "Create bot on homeserver, get access token from Element." Ask: Homeserver URL, access token (or user ID + password), enable E2EE?, allowed users (@user:server), home room (!room:server)

echo "MATRIX_HOMESERVER=" >> ~/.hermes/.env
echo "MATRIX_ACCESS_TOKEN=" >> ~/.hermes/.env
echo "MATRIX_ALLOWED_USERS=" >> ~/.hermes/.env
echo "MATRIX_HOME_ROOM=" >> ~/.hermes/.env
# If E2EE: echo "MATRIX_ENCRYPTION=true" >> ~/.hermes/.env
# Install: python3 -m pip install "mautrix[encryption]"

Mattermost

Guide: "Integrations → Bot Accounts → Add Bot → copy token." Ask: Server URL, bot token, allowed user IDs, home channel ID

echo "MATTERMOST_URL=" >> ~/.hermes/.env
echo "MATTERMOST_TOKEN=" >> ~/.hermes/.env
echo "MATTERMOST_ALLOWED_USERS=" >> ~/.hermes/.env
echo "MATTERMOST_HOME_CHANNEL=" >> ~/.hermes/.env

WhatsApp

Guide: "After config, run hermes whatsapp to choose mode (dedicated bot number vs personal self-chat) and pair via QR." Ask: Allowed phone numbers (E.164 format, e.g. 15551234567)

echo "WHATSAPP_ENABLED=true" >> ~/.hermes/.env
echo "WHATSAPP_ALLOWED_USERS=" >> ~/.hermes/.env

Signal

Guide: "Requires signal-cli running as HTTP daemon. Install: brew install signal-cli or from GitHub releases. Link account first: signal-cli link -n HermesAgent." Ask: HTTP URL (e.g. http://127.0.0.1:8080), phone number (E.164), allowed users, home channel

echo "SIGNAL_HTTP_URL=" >> ~/.hermes/.env
echo "SIGNAL_ACCOUNT=" >> ~/.hermes/.env
echo "SIGNAL_ALLOWED_USERS=" >> ~/.hermes/.env
echo "SIGNAL_HOME_CHANNEL=" >> ~/.hermes/.env

Email

Guide: "For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords" Ask: Email address, app password, IMAP host/port, SMTP host/port, allowed senders, home address

echo "EMAIL_ADDRESS=" >> ~/.hermes/.env
echo "EMAIL_PASSWORD=" >> ~/.hermes/.env
echo "EMAIL_IMAP_HOST=imap.gmail.com" >> ~/.hermes/.env
echo "EMAIL_IMAP_PORT=993" >> ~/.hermes/.env
echo "EMAIL_SMTP_HOST=smtp.gmail.com" >> ~/.hermes/.env
echo "EMAIL_SMTP_PORT=587" >> ~/.hermes/.env
echo "EMAIL_ALLOWED_USERS=" >> ~/.hermes/.env
echo "EMAIL_HOME_ADDRESS=" >> ~/.hermes/.env

DingTalk

Guide: "Create robot at https://open-dev.dingtalk.com → Stream Mode." Ask: Client ID, Client Secret, allowed user IDs

echo "DINGTALK_CLIENT_ID=" >> ~/.hermes/.env
echo "DINGTALK_CLIENT_SECRET=" >> ~/.hermes/.env
echo "DINGTALK_ALLOWED_USERS=" >> ~/.hermes/.env

Feishu / Lark

Guide: "Create app at https://open.feishu.cn/app → get App ID and Secret." Ask: App ID, App Secret, domain (feishu.cn or larksuite.com), connection mode (websocket default or webhook), allowed users, home channel

echo "FEISHU_APP_ID=" >> ~/.hermes/.env
echo "FEISHU_APP_SECRET=" >> ~/.hermes/.env
echo "FEISHU_DOMAIN=feishu.cn" >> ~/.hermes/.env
echo "FEISHU_CONNECTION_MODE=websocket" >> ~/.hermes/.env
echo "FEISHU_ALLOWED_USERS=" >> ~/.hermes/.env
echo "FEISHU_HOME_CHANNEL=" >> ~/.hermes/.env
# If webhook mode, also set:
# echo "FEISHU_ENCRYPT_KEY=" >> ~/.hermes/.env
# echo "FEISHU_VERIFICATION_TOKEN=" >> ~/.hermes/.env

WeCom (企业微信)

Ask: Bot ID, Secret, allowed users, home channel

echo "WECOM_BOT_ID=" >> ~/.hermes/.env
echo "WECOM_SECRET=" >> ~/.hermes/.env
echo "WECOM_ALLOWED_USERS=" >> ~/.hermes/.env
echo "WECOM_HOME_CHANNEL=" >> ~/.hermes/.env

Weixin (WeChat)

Guide: "Run hermes gateway setup → select Weixin. Scan QR code with WeChat to authenticate. Credentials stored automatically." This platform requires interactive QR login — cannot be configured via env vars alone.

BlueBubbles (iMessage)

Guide: "Requires BlueBubbles server on a Mac." Ask: Server URL, password, allowed users

echo "BLUEBUBBLES_SERVER_URL=" >> ~/.hermes/.env
echo "BLUEBUBBLES_PASSWORD=" >> ~/.hermes/.env
echo "BLUEBUBBLES_ALLOWED_USERS=" >> ~/.hermes/.env
echo "BLUEBUBBLES_HOME_CHANNEL=" >> ~/.hermes/.env

Webhooks (GitHub/GitLab)

Ask: Port (default: 8644), secret

echo "WEBHOOK_ENABLED=true" >> ~/.hermes/.env
echo "WEBHOOK_PORT=8644" >> ~/.hermes/.env
echo "WEBHOOK_SECRET=" >> ~/.hermes/.env

Install Gateway Service

If any platform configured:

hermes gateway install
hermes gateway start

• Linux: Creates systemd user service. Enable linger for SSH persistence: sudo loginctl enable-linger $USER. For system service (starts on boot): sudo hermes gateway install --system --run-as-user
• macOS: Creates launchd agent at ~/Library/LaunchAgents/ai.hermes.gateway.plist. Starts at login. Logs: ~/.hermes/logs/gateway.log
• WSL2: Requires systemd=true in /etc/wsl.conf. Without it, falls back to nohup (dies when session closes).

---

Section 5: Tools

Ask (multi-select): Which tools to enable?

| Tool | Env Var | Get Key | |------|---------|---------| | Web Search (Exa) | EXA_API_KEY | https://exa.ai | | Web Search (Tavily) | TAVILY_API_KEY | https://tavily.com | | Web Search (Parallel) | PARALLEL_API_KEY | https://parallel.ai | | Web Crawl (Firecrawl) | FIRECRAWL_API_KEY | https://firecrawl.dev | | Image Gen (FAL) | FAL_KEY | https://fal.ai | | Browser (Browserbase) | BROWSERBASE_API_KEY + BROWSERBASE_PROJECT_ID | https://browserbase.com | | Browser (Camofox) | CAMOFOX_URL | Self-hosted (see below) | | Browser (Browser Use) | BROWSER_USE_API_KEY | https://browser-use.com | | Voice STT (local) | None | Default, uses faster-whisper (~150MB model) | | Voice STT (Groq) | GROQ_API_KEY | https://groq.com | | Voice STT (OpenAI) | VOICE_TOOLS_OPENAI_KEY | https://platform.openai.com | | TTS | See below | Provider-specific | | X/Twitter | 5 keys | https://developer.x.com | | Home Assistant | HASS_TOKEN + HASS_URL | Your HA instance | | Skills Hub search | GITHUB_TOKEN | https://github.com/settings/tokens | | Honcho (user modeling) | HONCHO_API_KEY | https://app.honcho.dev |

TTS providers — set with hermes config set tts.provider :

• edge (default, free, no key)
• elevenlabs (requires ELEVENLABS_API_KEY)
• openai (requires VOICE_TOOLS_OPENAI_KEY)
• minimax (requires MINIMAX_API_KEY)
• neutts (local/offline, requires espeak-ng system package + ~300MB model)

STT providers — set with hermes config set stt.provider :

• local (default, faster-whisper, no key)
• groq (requires GROQ_API_KEY)
• openai (requires VOICE_TOOLS_OPENAI_KEY)

For each selected tool: ask for key, write to ~/.hermes/.env, then chmod 600 ~/.hermes/.env.

Camofox self-hosted browser:

git clone https://github.com/jo-inc/camofox-browser.git ~/camofox-browser
cd ~/camofox-browser && npm install
nohup node server.js

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hqhq1025](https://github.com/hqhq1025)
- **Source:** [hqhq1025/hermes-setup-skill](https://github.com/hqhq1025/hermes-setup-skill)
- **License:** MIT
- **Homepage:** https://github.com/hqhq1025/hermes-setup-skill

Install and usage instructions live in the source repository linked above.