Hermes Setup

This page gets a Hermes + Kirimdev gateway running. For nginx, SSL, systemd, and hardening, follow the plugin’s production DEPLOY.md after the steps below.

Treat keys like production

The API key and webhook secret you configure on Hermes can send WhatsApp messages and receive every inbound event for your org. Use a dedicated key per gateway and revoke it when the VPS is decommissioned.

Prerequisites

Item	Notes
Kirimdev account	WhatsApp Cloud API number connected
API key	kdv_live_… from Dashboard → Settings → API Keys
phone_number_id	Meta business phone number ID (Settings → WhatsApp number)
Hermes Agent	v0.14.0+ with an LLM provider configured (hermes doctor)
Public HTTPS URL	Dedicated subdomain pointing at your gateway (production)

Install

1. Install Hermes Agent on your server or dev machine.

   Follow the official Hermes install guide, then verify:

   hermes --version
   hermes doctor

2. Copy the Kirimdev plugin into Hermes’ plugin directory.

   git clone https://github.com/kirimdev/kirimdev-hermes.git
   cp -r kirimdev-hermes/kirimdev-platform ~/.hermes/plugins/kirimdev-platform
   hermes plugins enable kirimdev-platform

   Install Python deps in the Hermes environment:

   pip install aiohttp httpx
   # or: ~/.hermes/hermes-agent/venv/bin/pip install aiohttp httpx

3. Set required configuration.

   hermes config set KIRIMDEV_API_KEY kdv_live_xxxxxxxx
   hermes config set KIRIMDEV_ENABLED_NUMBERS 123456789012345
   hermes config set KIRIMDEV_DEFAULT_PHONE_NUMBER_ID 123456789012345
   hermes config set KIRIMDEV_PUBLIC_URL https://hermes-webhooks.example.com
   hermes config set KIRIMDEV_OWNER_USERS 628123456789

   Variable	Required	Purpose
   KIRIMDEV_API_KEY	✅	Public API bearer token
   KIRIMDEV_WEBHOOK_SECRETS	✅	Set after Step 5 (whsec_…)
   KIRIMDEV_ENABLED_NUMBERS	✅	Comma-separated phone_number_id values Hermes may operate
   KIRIMDEV_DEFAULT_PHONE_NUMBER_ID	Recommended	Default sender for cron / CLI
   KIRIMDEV_PUBLIC_URL	Recommended	Public base URL (no /webhook suffix)
   KIRIMDEV_OWNER_USERS	Recommended	Owner phones (digits, no +)
   KIRIMDEV_ALLOWED_USERS	Optional	Whitelist for instant replies
   KIRIMDEV_OWNER_FULL_AGENT	Optional	Default true — see overview
   KIRIMDEV_API_BASE_URL	Optional	Default https://api.kirimdev.com/v1 — leave unset for production

4. Start the gateway.

   hermes gateway run
   # production: systemd user unit — see plugin DEPLOY.md

   Verify locally:

   curl -s http://127.0.0.1:8646/health
   # {"status":"ok","platform":"kirimdev","channel":"whatsapp"}

5. Create a Kirimdev webhook subscription pointing at your gateway.

   Dashboard

   Dashboard → Settings → Webhooks → create subscription:

   • URL: https://hermes-webhooks.example.com/webhook
   • Events: message.received

   Copy the signing secret (whsec_…).

   API

   curl -s -X POST https://api.kirimdev.com/v1/webhook_subscriptions \
     -H "Authorization: Bearer $KIRIMDEV_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://hermes-webhooks.example.com/webhook",
       "events": ["message.received"]
     }'

   Save initial_secret from the response. See Subscribe to Webhooks for signature verification details.

   Configure Hermes and restart:

   hermes config set KIRIMDEV_WEBHOOK_SECRETS whsec_xxxxxxxx
   systemctl --user restart hermes-gateway   # if using systemd

6. Smoke test.

   Send a WhatsApp message from a number listed in KIRIMDEV_OWNER_USERS to your business line. You should see inbound logs and an agent reply.

   If nothing responds, check tier config — unknown senders require owner approval. See Authorization tiers in the overview.

Production checklist

• nginx reverse-proxy 443 → 127.0.0.1:8646; do not expose :8646 publicly.
• TLS via Let’s Encrypt (certbot).
• systemd user unit with Restart=on-failure — template in hermes-gateway.service.
• Firewall — allow 80/443 only.
• Secret rotation — add comma-separated secrets to KIRIMDEV_WEBHOOK_SECRETS during overlap; see Verifying Signatures.

Troubleshooting

Symptom	Likely cause	Fix
401 on webhook	Wrong whsec_	Match KIRIMDEV_WEBHOOK_SECRETS to subscription
Inbound logged, no reply	Sender is unknown tier	Add to KIRIMDEV_OWNER_USERS or approve via WA button
phone_number_id not enabled	ID mismatch	Fix KIRIMDEV_ENABLED_NUMBERS
No typing indicator	API or plugin version	Plugin v1.0.0+; Kirimdev API with typing-on-read support
502 from nginx	Gateway down	systemctl --user status hermes-gateway

Related

• Hermes overview — architecture, use cases, MCP comparison
• Receive messages — webhook payload shape
• Mark as read — read receipts + typing indicator API
• MCP Setup — assistant-driven integration (no VPS gateway)