moonlight-lupin/agent-skills/hermes-onboarding

Hermes Onboarding

Configure a fresh Hermes Agent from a working base chat to a production-ready deployment.

Precondition: Hermes is installed and the main model + provider are configured. Verify with hermes doctor. If the agent cannot complete a normal chat, stop here and fix the provider first.

Leading word: onboard — configure every layer before declaring the setup complete.

When to Use

• A customer has a fresh Hermes install with a working base chat and needs full configuration
• An operator is setting up Hermes on a new VPS or machine for production use
• A customer wants to go from "it works" to "it is secured, memory-enabled, always-on, and maintained"

Do not use if the main model is not yet configured. Fix the provider first.

Step 0 — Load references

Load references/setup-details.md. It holds config snippets, systemd templates, DonSeTch MCP config, skill guardrail principles, and verbosity examples.

Done: references file loaded into context.

Step 1 — Detect environment

Run the detection block from references/setup-details.md § Detection. Collect:

Done: all 8 items detected and recorded. No user input required.

Step 2 — Ask up-front questions

Ask the customer 3 questions in one batch:

1. Customer name — used for profile name and soul.md identity
2. Timezone — IANA timezone (e.g. Asia/Singapore, America/New_York)
3. Gateway platform(s) — Telegram, Discord, WhatsApp, Slack, Signal. Collect bot tokens or pairing info. Tokens are stored in ~/.hermes/.env (chmod 600). Do not paste tokens into chat transcripts.

If Step 1 detected the main model lacks vision, add a 4th question:

1. Vision-capable aux model — which model + provider for vision tasks? Default: same provider as main.

Done: all up-front questions answered. Conditional vision question asked only if needed.

Step 3 — Alternative providers and aux models

If no NVIDIA_API_KEY: help customer get a free key at https://build.nvidia.com/nvidia/nemotron-3-embed-1b. Fallback: OpenRouter bge-m3 using existing OPENROUTER_API_KEY.

Done: aux vision model configured (if needed). NVIDIA_API_KEY set. Delegation confirmed as following main model.

Step 4 — Profile and soul.md

1. Create single profile: hermes profile create <customer-name>
2. Ask customer for soul.md input:

• Agent name (default: "Hermes")
• Preferred language (default: English)
• Personality (default: business)
• Domain-specific instructions (optional)

1. Write ~/.hermes/SOUL.md from customer input. See references/setup-details.md § Soul.md template.

Multi-profile: only if customer specifically mentions needing separate profiles.

Done: profile created. soul.md written with customer's input.

Step 5 — Gateway and services

1. Configure gateway: hermes gateway setup — select customer's chosen platform(s), enter tokens
2. Deploy gateway as systemd service. Use template from references/setup-details.md § Gateway systemd unit:

• Root mode: /etc/systemd/system/hermes-gateway.service
• User mode: ~/.config/systemd/user/hermes-gateway.service + loginctl enable-linger $USER
• Set TimeoutStopSec=240

1. Deploy dashboard as systemd service. Use template from references/setup-details.md § Dashboard systemd unit:

• Set HERMES_DASHBOARD_TUI=1
• Set HERMES_PYTHON to venv python path
• Binding choice — ask the customer:
• Loopback (default): bind to 127.0.0.1. Access via SSH tunnel: ssh -L 9119:127.0.0.1:9119 user@host. Most secure. No firewall change needed.
• LAN (0.0.0.0): bind to all interfaces with --host 0.0.0.0. Direct access from any device on the same network at http://<host-ip>:9119. Suitable for internal WiFi/LAN where all devices are trusted. Set up basic auth (Step 5b) so the dashboard is not unprotected.

1. Enable and start both services
2. Set timezone: hermes config set timezone '<customer-timezone>' + timedatectl set-timezone '<tz>'

Done: gateway and dashboard running as systemd services. Test message sent through gateway. Dashboard accessible via SSH tunnel or LAN with basic auth.

Step 5b — Dashboard basic auth (required for LAN mode, recommended for all)

Hermes has a built-in basic auth provider. Set a username and password so the dashboard is not unprotected.

1. Hash the password:

``bash python3 -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('customer-password'))" ``

1. Set in config.yaml (edit directly — hermes config set stringifies nested values):

``yaml dashboard: basic_auth: username: admin password_hash: <hash-from-step-1> ``

1. Restart dashboard: systemctl restart hermes-dashboard
2. Verify: open dashboard URL in browser — should show login page

For loopback-only deployments this is optional (SSH tunnel already gates access). For LAN deployments this is required.

Done: basic auth configured. Dashboard shows login page when accessed.

Step 6 — Approvals and terminal backend

Done: approvals set to smart. Terminal backend set based on Docker detection.

Step 7 — Compression

Set compression based on model context length:

hermes config set compression.enabled true
hermes config set compression.threshold <value>
hermes config set compression.target_ratio 0.20

Done: compression enabled with threshold matched to model context length.

Step 8 — Search and fetch backend (DonSeTch + fallback)

Primary: DonSeTch MCP server (mcp_donsetch_web_search / web_fetch / web_crawl). It handles research-grade queries, bot-walled pages, and JS-rendered content. Install and wire it, then set a lightweight fallback for single-fact lookups.

8a — Install DonSeTch

npm install -g donsetch

8b — Register as MCP server

Add to mcp: in ~/.hermes/config.yaml (edit directly — hermes config set stringifies nested values):

  donsetch:
    command: /usr/local/lib/node_modules/donsetch/binaries/donsetch
    args:
      - mcp
      - --supervised
    env:
      DONGHOST_CHROME: /usr/bin/google-chrome-stable
      DONGHOST_NO_SANDBOX: '1'
    enabled: true

Verify: hermes plugins list or session info shows donsetch with 3 tools connected. Test with a query through mcp_donsetch_web_search.

8c — Fallback backend (keyless Firecrawl)

Set web.search_backend: firecrawl in config. With no FIRECRAWL_API_KEY set, Hermes uses Firecrawl's anonymous public cloud mode (api.firecrawl.dev, no auth header) — verified: explicit selection + no credentials routes to keyless, zero install steps. It supports both search and extraction.

If the customer later buys a Firecrawl plan, set FIRECRAWL_API_KEY — the same backend upgrades to keyed mode automatically, no config change.

Alternatives only if the customer objects to anonymous cloud calls:

• Docker available: deploy SearXNG (references/setup-details.md § SearXNG deployment), set web.search_backend: searxng
• No Docker: pip install ddgs, set web.search_backend: ddgs

The fallback serves single-fact quick lookups (one URL, one version, one price) and covers the case where DonSeTch is down.

8d — Web-routing rules in SOUL.md

Write the web-routing section into the customer's SOUL.md at Step 4 (soul.md write), not later. Use the template in references/setup-details.md § Web tool routing (SOUL.md template). Core rules:

• Research or precision search, comparisons, multi-source verification → mcp_donsetch_web_search FIRST
• Built-in web_search = single-fact quick lookup ONLY
• Bot-walled, captcha-adjacent, or JS-rendered URL → mcp_donsetch_web_fetch; built-in web_extract = plain pages only
• Site-wide inventory → mcp_donsetch_web_crawl
• Authenticated sites, file uploads, interactive flows → browser_exec
• Scanned-PDF/OCR → pdftoppm + tesseract, not donsetch
• LAN/loopback URLs → built-ins (donsetch SSRF-blocks them)

8e — DonSeTch weekly update cron

Install the release-binary self-updater (no source builds — lighter dependency footprint):

# Script ships with the onboarding skill
cp ~/.hermes/skills/agent-ops/hermes-onboarding/scripts/donsetch_update.sh ~/.hermes/scripts/
chmod +x ~/.hermes/scripts/donsetch_update.sh
hermes cron create --name "DonSeTch weekly update" --schedule "0 9 * * 1" --mode no_agent ~/.hermes/scripts/donsetch_update.sh

The script gates on GitHub releases/latest (published releases with assets), NOT tags — a tag without published assets makes donsetch update 404. Silent (empty stdout) when already latest: the no_agent cron only alerts on failure or update.

If customer has Nous Portal: Tool Gateway search is already active. Still install DonSeTch + fallback — Tool Gateway search does not fetch bot-walled pages.

Done: DonSeTch installed and connected as MCP server (3 tools). Fallback backend set. Web-routing rules written into SOUL.md. Update cron armed. Search verified with a test query.

Step 9 — Extraction

Verify keyless extraction works. Step 1 recorded the Hermes version — confirm it is 0.20.5+ for the keyless MCP ring (exa, parallel, tavily, firecrawl, keenable):

hermes chat -q "Extract the content from https://example.com"

If the extraction succeeds, no action needed. If customer wants a pinned backend, set web.extract_backend: firecrawl — keyless anonymous mode works with no API key (same mechanism as Step 8c); set FIRECRAWL_API_KEY later to upgrade to keyed.

Done: keyless extraction verified working.

Step 10 — Memory (Mnemosyne)

1. Enable Mnemosyne: hermes memory setup → select Mnemosyne
2. Confirm NVIDIA_API_KEY is set (from Step 3) — Mnemosyne uses it for embeddings
3. Verify memory works: mnemosyne_recall({"query": "test", "limit": 1})

Done: Mnemosyne enabled. Embedding key confirmed. Memory recall verified.

Step 11 — Skill writing guardrails

Apply the 7 Matt Pocock principles to self-generated skills. See references/setup-details.md § Skill guardrails. The agent should review any skill it creates against these principles.

For full skill authoring validation, load the bundled skill: skill_view(name='hermes-agent-skill-authoring'). This is a Hermes-bundled skill — it ships with every install under the software-development category.

Done: guardrail principles loaded. Agent knows where to find full skill authoring validation.

Step 12 — Skill retrieval plugin (BM25)