OpenAB Hermes

OpenAB is a lightweight, open-source Rust harness that bridges Discord and Slack to any Agent Client Protocol-compatible coding CLI over stdio JSON-RPC.

This template runs the Hermes variant: it uses Hermes Agent by Nous Research as the backend. Hermes is a multi-provider inference gateway — it handles OAuth token lifecycle, credential storage, and routing for 30+ LLM providers (xAI Grok, Anthropic, OpenAI, Nous Portal, and more), so OAB doesn't need to manage provider auth directly.

Important Notes

• Image tag: This template uses a pinned version (0.8.3-beta.10). To upgrade, change the image tag in Zeabur Dashboard → Service → Settings. Available tags: GitHub Packages.
• Persistent storage: /home/agent is mounted as a persistent volume. Hermes credentials, plugins, settings, and config survive restarts.
• Authentication is in-container only: Hermes auth is OAuth-based per provider. There is no single API key variable — after deploying, run hermes auth add <provider> inside the service to pair with each LLM provider you want.

Setup

1. Get a Discord Bot Token

1. Go to https://discord.com/developers/applications and click New Application
2. Navigate to Bot tab → click Reset Token → copy the token
3. On the same page, scroll down and enable Message Content Intent under Privileged Gateway Intents
4. Go to OAuth2 → URL Generator → check scope bot → check permissions: Send Messages, Send Messages in Threads, Create Public Threads, Read Message History, Add Reactions, Manage Messages
5. Copy the generated URL and open it in your browser to invite the bot to your server

2. Get Discord Channel IDs

1. Open Discord → go to User Settings (gear icon) → Advanced → enable Developer Mode
2. Right-click the channel where you want the bot to respond → Copy Channel ID
3. For multiple channels, separate IDs with commas: 123456789012345678,234567890123456789

3. Deploy

Fill in the variables and click deploy. The service connects to Discord but will not produce LLM responses until you authenticate at least one provider (step 4).

4. Authenticate a Hermes Provider

After the service is running, open the Zeabur Dashboard → Service → Exec terminal. Hermes supports many providers — pick one to start. Two of the most common paths are below.

Option A: Nous Portal (simplest)

runuser -u agent -- hermes auth add nous

Follow the prompts to complete OAuth via the displayed URL.

Option B: xAI Grok OAuth (recommended for general use)

⚠️ Requires an active SuperGrok paid subscription ($30/mo). Auth will succeed without one, but the API silently returns empty responses — the bot appears to work but never replies.

xAI's OAuth uses a loopback redirect to 127.0.0.1:56121 inside the container. Zeabur doesn't expose that port, so use the two-terminal trick:

Terminal 1 — start the auth listener:

runuser -u agent -- hermes auth add xai-oauth --no-browser

It prints an authorize URL containing &state=XXXXX and waits on http://127.0.0.1:56121/callback.

In your browser — open that authorize URL → approve. The browser redirects to http://127.0.0.1:56121/callback?code=... and fails ("Could not establish connection"). Copy the code value from the URL bar.

Terminal 2 — open another Exec session and deliver the callback locally:

runuser -u agent -- curl "http://127.0.0.1:56121/callback?code=<CODE>&state=<STATE>"

Terminal 1 should print Added xai-oauth OAuth credential #1. The code expires in seconds — if you see invalid_grant, re-run hermes auth add xai-oauth and try again.

After auth: pick a default model

Either run the interactive picker:

runuser -u agent -- hermes model

…or set provider and model as two separate keys (this is what hermes-acp needs — the combined provider/model shortcut shown in hermes config set examples is for the standalone CLI and is not picked up by openab):

runuser -u agent -- hermes config set provider xai-oauth
runuser -u agent -- hermes config set model grok-4-latest

Your choice is persisted under /home/agent and survives restarts. New Discord sessions pick up the new model automatically — no restart needed.

For other providers (Anthropic, OpenAI, etc.) see the Hermes Agent docs.

Slack Setup (Optional)

OpenAB supports Slack via Socket Mode — no public URL needed.

1. Go to https://api.slack.com/apps → Create New App → From scratch
2. Socket Mode → Enable → generate an App-Level Token with scope connections:write → copy the xapp-... token (SLACK_APP_TOKEN)
3. Event Subscriptions → Enable Events → add bot events: app_mention, message.channels, message.groups
4. OAuth & Permissions → Bot Token Scopes → add: app_mentions:read, chat:write, channels:history, groups:history, channels:read, groups:read, reactions:write, files:read, users:read
5. Install App → Install to Workspace → copy the xoxb-... token (SLACK_BOT_TOKEN)
6. In each Slack channel you want the bot in, run /invite @YourAppName

Set SLACK_BOT_TOKEN and SLACK_APP_TOKEN in the template variables before deploying. Both Discord and Slack can run simultaneously.

Add Messaging Platforms (Telegram / LINE / Feishu / Google Chat / MS Teams / WeCom)

To bridge Telegram, LINE, Feishu/Lark, Google Chat, MS Teams, or WeCom, deploy the OpenAB Gateway template into the same Zeabur project. Then add these environment variables to this service:

• GATEWAY_URL = ws://openab-gateway:8080/ws
• GATEWAY_PLATFORM = one of telegram, line, feishu, googlechat, teams, wecom

Restart the service. The startup script auto-injects the [gateway] block into config.toml.

Usage

• @mention the bot in an allowed Discord channel or Slack channel to start a conversation
• OpenAB creates a thread for multi-turn conversations — no @mention needed for follow-ups
• Each thread maps to a persistent Hermes session (24h TTL)

Customization

File	Description
/home/agent/.config/openab/config.toml	OpenAB config (sessions, reactions, STT, etc.)
/home/agent/.config/hermes/	Hermes credentials and provider config (managed by hermes auth / hermes model)

config.toml is created from a built-in template on first boot. After that, edit the file directly — environment variables are only used for initial setup. To reset to defaults, delete the file and restart: rm /home/agent/.config/openab/config.toml

For OpenAB config options, see the OpenAB documentation. For Hermes provider options, see the Hermes docs.

Disabling

Leave Discord Bot Token empty (and SLACK_BOT_TOKEN empty). The service sleeps instead of crashing.

Links

• OpenAB GitHub
• Hermes Agent (Nous Research)
• Agent Client Protocol