✦
Hermes Agent
Open navigation menu

How-To Guide

How to Connect Hermes Agent to Slack with Socket Mode

Connect Hermes Agent to Slack with the generated app manifest, Socket Mode tokens, user and channel allowlists, thread commands, cron delivery, and exact troubleshooting checks.

Quick answer

Run hermes slack manifest --agent-view --write, create the Slack app from that manifest, install it, and give Hermes both the xoxb- bot token and xapp- Socket Mode token. Then allowlist Slack Member IDs and channels, start the gateway, invite the bot, and prove one real DM and channel reply. Socket Mode means no public webhook URL is required.

Hermes connects to Slack through the modern Bolt SDK and Socket Mode. Slack sends app events over a WebSocket, so you do not need a public callback URL, ngrok tunnel, or internet-facing dashboard. You do need two tokens, explicit access controls, a continuously running Hermes gateway, and an end-to-end channel test.

Deploy Hermes faster with FlyHermes

Managed cloud · API costs included · Skill library · Cancel anytime

Before you start:

  • ☑A current Hermes Agent installation with the hermes slack manifest and gateway commands
  • ☑Permission to create and install an app in the target Slack workspace
  • ☑Slack Member IDs for every user you intend to authorize
  • ☑A laptop, private server, or managed runtime that can keep the Socket Mode gateway online — no public URL required

Steps

  1. 1

    Generate the Hermes Slack app manifest

    Run hermes slack manifest --agent-view --write. Hermes writes ~/.hermes/slack-manifest.json with the current OAuth scopes, event subscriptions, Socket Mode setting, and native slash commands.

  2. 2

    Create the Slack app from the manifest

    Open api.slack.com/apps, choose Create New App → From an app manifest, select the workspace, paste the generated JSON, review it, and create the app.

  3. 3

    Create the Socket Mode app token

    In Settings → Socket Mode, enable Socket Mode and create an app-level token with connections:write. Copy the xapp- value; this is SLACK_APP_TOKEN.

  4. 4

    Install the app and copy the bot token

    Install the app to the workspace and copy the Bot User OAuth Token beginning xoxb-; this is SLACK_BOT_TOKEN. Reinstall after any later scope, event, or command change.

  5. 5

    Allowlist Slack users and channels

    Copy authorized Slack Member IDs and run hermes gateway setup, or set SLACK_ALLOWED_USERS. Optionally set SLACK_ALLOWED_CHANNELS and SLACK_HOME_CHANNEL. Hermes denies Slack messages by default when no users are authorized.

  6. 6

    Start the Hermes gateway

    Run hermes gateway in the foreground for the first test or install the gateway as a service. Confirm the gateway starts with both Slack tokens and the intended Hermes profile.

  7. 7

    Invite and mention Hermes in one test channel

    Run /invite @Hermes Agent in the test channel, then send @Hermes Agent reply with the active profile name. In channels, an explicit mention starts the conversation.

  8. 8

    Test DMs, threads, commands, and scheduled delivery

    Verify a 1:1 DM, a channel thread reply, a top-level slash command, a thread !command, and any cron report in its exact destination before adding more channels or tools.

Pro Tips

  • 💡Use hermes slack manifest --agent-view --write for a new app; after Hermes updates, run hermes slack manifest --write, replace the saved App Manifest, and reinstall if Slack prompts you.
  • 💡Set SLACK_ALLOWED_USERS with Member IDs, not display names. Add SLACK_ALLOWED_CHANNELS when the bot should operate only in named team surfaces.
  • 💡Use native /commands at top level. Inside Slack threads, use the Hermes !command form because Slack blocks native slash commands there.
  • 💡Keep group_sessions_per_user: true for separate teammate context. Turn it off only for a deliberately shared channel session where shared resets and token growth are acceptable.
  • 💡Set SLACK_HOME_CHANNEL for scheduled reports and prove a real cron delivery before depending on it.
  • 💡If your team needs connected-channel uptime but does not want to own gateway services, updates, provider keys, and delivery monitoring, compare FlyHermes with the self-hosted route.

Troubleshooting

❌ Hermes works in DMs but not public or private channels

✅ Add message.channels for public channels and message.groups for private channels, add the corresponding channels:history or groups:history scope, reinstall the app, invite the bot, and start with an @mention.

❌ Slack says sending messages to this app is turned off

✅ Open Features → App Home, enable the Messages Tab, and allow users to send slash commands and messages from that tab.

❌ Hermes commands are missing after an update

✅ Run hermes slack manifest --write, replace the JSON under Features → App Manifest, save it, and reinstall the app if scopes or slash commands changed.

❌ Slash commands fail inside Slack threads

✅ This is a Slack platform limit, not a Hermes gateway failure. Use !queue, !stop, !model, !approve, !deny, or another known !command as a normal thread reply.

❌ The bot chats but cannot read uploaded files

✅ Add the files:read scope and reinstall the app. Use files:write only when Hermes must upload files back into Slack.

❌ Slack events are delayed or duplicated after adding an action sidecar

✅ Do not let two Socket Mode consumers compete for one envelope. Keep one event owner, or use an external interaction bridge that acknowledges immediately, filters known action IDs, and deduplicates before triggering Hermes.

❌ Gateway is connected but Hermes still ignores a channel

✅ Check SLACK_ALLOWED_USERS, SLACK_ALLOWED_CHANNELS, channel membership, @mention gating, the active profile, and gateway logs. A connected WebSocket does not prove routing or authorization.

❌ Cron runs but no Slack report appears

✅ Set an explicit Slack delivery target or SLACK_HOME_CHANNEL, invite the bot to that channel, verify the job status and delivery error fields, and run one harmless manual test.

FAQ

Does Hermes Slack need a public webhook URL?

No. Hermes uses Slack Socket Mode, which sends events over a WebSocket. Your Hermes runtime can stay on a laptop, behind a firewall, or on a private server.

What tokens are required for Hermes Slack?

You need a Bot User OAuth Token beginning xoxb- and an App-Level Token beginning xapp- with connections:write for Socket Mode.

Why must I reinstall the Slack app after a scope or event change?

Slack does not apply new OAuth scopes, event subscriptions, or slash commands to the installed app automatically. Reinstall when the App Manifest or permissions change.

How do Hermes commands work in Slack threads?

Slack blocks native slash commands inside thread replies. Use the matching !command form, such as !queue, !stop, !model, !approve, or !deny.

Can Hermes Agent post scheduled reports to Slack?

Yes. Set an explicit Slack delivery target or SLACK_HOME_CHANNEL, invite the bot, and verify one real test delivery before relying on production reports.

How do I keep different teammates' Slack context separate?

Keep group_sessions_per_user: true, the default, so each user has isolated conversation history in a shared channel. Use a shared session only when the team intentionally accepts shared context and resets.

Related setup and cost guides

Hermes Agent Slack integration overview

Understand team workflows, threads, access controls, scheduled delivery, and the managed-cloud decision.

Hermes Web UI

Monitor gateway and cron health.

Hermes gateway troubleshooting

Diagnose a connected service that still fails real channel delivery.

Hermes profiles for team bots

Isolate Slack secrets, tools, memory, skills, and gateway state.

Reliable Slack cron delivery

Schedule reports with explicit delivery targets and status checks.

Related Guides

slackhermes agent gateway troubleshootinghermes agent profiles guidehermes agent cron jobspricing