How to Set Up Hermes Agent on Slack (Socket Mode)

Why Run Hermes Agent in Slack

If your team already lives in Slack, that is where your AI agent should live too. Browser tabs and standalone dashboards lose the context that channels, threads, and direct messages already give for free: who is asking, what they were just talking about, and where the answer should land.

Hermes Agent ships first-class Slack support over Socket Mode, so the runtime can sit on your laptop, on a $5 VPS, or behind a corporate firewall and still stream messages in real time. There is no public webhook to expose, no reverse proxy to maintain, and no inbound port to open. The agent connects out to Slack, holds a WebSocket open, and delivers every message and response over that single channel.

This guide walks through the full setup end to end: creating the Slack app from the bundled manifest, generating bot and app-level tokens, wiring up the home channel and allowlist, starting the gateway, and the failure modes that bite first-time deployments.

What You Need Before You Start

A clean Slack deployment needs five things in place:

A workspace where you have permission to install apps. Most workspaces require an admin to approve installs by default - check Settings & administration → Workspace settings → Permissions if you are not an admin.
A running Hermes Agent install. The Hermes Agent Docker guide covers the cleanest way to get one up; if you are on Windows, the WSL2 setup is the equivalent.
A model provider key. Anthropic, OpenAI, OpenRouter, and any OpenAI-compatible endpoint all work. The runtime uses this to actually answer the messages.
Your numeric Slack user ID for the allowlist (more on this below).
About 15 minutes for the first install. Subsequent re-deployments take under a minute.

Step 1 - Generate the Slack App Manifest

Slack apps are defined by a YAML manifest that declares scopes, event subscriptions, slash commands, and Socket Mode in one shot. Hermes ships a manifest tailored to its built-in Slack handler, so you do not have to assemble the scope list by hand:

hermes slack manifest --write ./hermes-slack-manifest.yaml

Open https://api.slack.com/apps, click Create New App, choose From an app manifest, pick your workspace, and paste the contents of hermes-slack-manifest.yaml. Slack previews exactly what will be created. Confirm.

The manifest enables Socket Mode, declares every event Hermes subscribes to (app_mention, message.im, message.channels, message.groups, message.mpim), registers the built-in slash commands, and asks for the bot scopes the runtime actually uses:

app_mentions:read - hear when someone @-mentions the bot in a channel.
chat:write - send replies and start threads.
im:history, im:read, im:write - direct-message conversations.
channels:history, groups:history, mpim:history - read context in public channels, private channels, and group DMs the bot is invited to.
users:read - resolve user IDs into display names for the allowlist UI and audit logs.
commands - register the /hermes slash command surface.

Editing the manifest after install is fine. Adding scopes after install is the operation that causes the most quiet failures - see the troubleshooting section below.

Step 2 - Generate the Bot Token and App-Level Token

Slack issues two distinct tokens for a Socket Mode app, and Hermes needs both:

Bot token (xoxb-…)

In the app settings, go to OAuth & Permissions → Install to Workspace. Approve the scopes from the manifest. Slack issues a xoxb-… token. Copy it.

App-level token (xapp-…)

Go to Basic Information → App-Level Tokens → Generate Token and Scopes. Name it (e.g. hermes-socket), add the connections:write scope, and click Generate. Slack issues a xapp-… token. Copy it.

The two tokens do different jobs. The bot token authenticates Slack API calls (sending a message, reading channel history). The app token authenticates the Socket Mode WebSocket itself - without it, the runtime starts but never connects to Slack and the bot stays silent forever.

Step 3 - Find Your Numeric Slack User ID

Hermes Agent will only respond to user IDs that appear in SLACK_ALLOWED_USERS. This is the single most important security control in the whole setup, and it expects numeric IDs, not @handles or display names.

In Slack, click your avatar → Profile → the kebab menu (⋮) → Copy member ID. The ID looks like U01ABCD2EFG. Repeat for any teammate you want to authorise.

Skipping the allowlist is the same as publishing your provider API key to anyone in your workspace. If a Hermes instance is reachable from a public Slack workspace and the allowlist is empty, every message in every channel the bot is invited to will burn your tokens.

Step 4 - Configure the Hermes Runtime

Open ~/.hermes/.env (or whichever .env your container reads) and add:

SLACK_BOT_TOKEN=xoxb-...your-bot-token...
SLACK_APP_TOKEN=xapp-...your-app-token...
SLACK_ALLOWED_USERS=U01ABCD2EFG,U02HIJK3LMN
SLACK_HOME_CHANNEL=C04XYZ123AB

A note on each:

SLACK_BOT_TOKEN - the xoxb-… token from Step 2.
SLACK_APP_TOKEN - the xapp-… token. Forgetting this is the most common failure mode and it produces no error message - the gateway simply never opens the WebSocket.
SLACK_ALLOWED_USERS - comma-separated list of numeric IDs. The bot ignores everyone else, including admins and bot accounts.
SLACK_HOME_CHANNEL (optional) - the channel ID for proactive messages, scheduled summaries, and skill-triggered notifications. Right-click the channel in Slack → View channel details → copy the channel ID at the bottom. If unset, proactive output goes to the bot's DM with the first allowed user.

chmod 600 ~/.hermes/.env after saving. Both tokens grant write access to your workspace; treat them like SSH keys.

A terminal showing the Hermes .env file with SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_ALLOWED_USERS, and SLACK_HOME_CHANNEL filled in, with file permissions hardened to 600

Step 5 - Start the Gateway

Restart the gateway so it picks up the new environment:

hermes gateway restart

Or, with Docker Compose:

docker compose restart gateway

Tail the logs and watch for the Slack handshake:

hermes gateway logs --follow

You are looking for two lines, in order:

slack: connecting to Socket Mode
slack: connected as @your-bot-name (workspace: your-workspace)

If you see only the first line and nothing after, the xapp-… token is wrong, missing, or lacks the connections:write scope. If you see neither, the gateway is not picking up the new .env - confirm the file path the runtime reads.

Step 6 - Invite the Bot and Send the First Message

In any channel where you want the bot to participate:

/invite @your-bot-name

The bot only sees messages in channels it has been invited to. This is a Slack-side restriction, not a Hermes one - even with channels:history granted, the bot reads zero history until you /invite it.

Send a DM to the bot, or @-mention it in the channel. Hermes responds in the same conversation, with full memory and skill context intact. From here, every Hermes capability - persistent memory, scheduled tasks, custom skills - works exactly as it does on the Telegram delivery surface.

A Slack channel showing a thread between a user and the Hermes bot, with the bot replying contextually and a small green online indicator beside the bot's name

The Failure Modes That Bite First

Five mistakes account for almost every "Slack setup is broken" support thread:

Forgetting the xapp-… token. Socket Mode does not connect at all without it, and Slack's app dashboard does not warn you. The fix is one line in .env and a restart.

Adding scopes after install without reinstalling. New scopes appear in the OAuth page but are not actually granted to the bot until you click Reinstall to Workspace. The bot keeps the old scope set silently. If the runtime logs missing_scope errors, this is why.

Bot not invited to the channel. A bot with channels:history still reads no history until invited. The bot will respond to DMs immediately but stay silent in channels until /invite @your-bot-name is run.

Empty SLACK_ALLOWED_USERS. The default is to ignore everyone. This is a deliberate safe default, but it makes the bot look broken to a first-time tester who forgot to add their own ID.

Two gateway processes against the same data volume. If you start a Slack-mode gateway and a Telegram-mode gateway against the same /data directory, message ordering and memory writes corrupt each other within minutes. Run a single gateway with both SLACK_* and TELEGRAM_* blocks set in .env if you want both surfaces - the runtime multiplexes both natively.

If a problem looks Slack-shaped but the symptoms feel general, the Telegram troubleshooting guide covers the underlying gateway and provider issues in more depth - most are surface-agnostic.

Slack and Telegram, Side by Side

| Concern | Slack | Telegram | |---|---|---| | Setup time | 15 min (manifest + 2 tokens) | 5 min (one BotFather token) | | Reachability | Behind firewall (Socket Mode WebSocket) | Behind firewall (long-poll) | | Allowlist field | SLACK_ALLOWED_USERS (numeric IDs) | TELEGRAM_ALLOWED_USERS (numeric IDs) | | Best for | Team workflows, channel context, threads | Personal use, mobile-first, voice-mode | | Threading | Native | Quote replies only | | File handling | Built-in uploads + previews | Built-in uploads + previews |

The two surfaces are not exclusive. The same Hermes runtime can deliver to both at the same time - useful when the same agent serves a personal Telegram chat and a team Slack channel from the same memory store.

Skip the Slack Plumbing

The Slack steps themselves are straightforward, but you still own the host: backups, TLS for the dashboard, log rotation, and the upgrade cadence. For a personal-scale install that is fine. For a team that wants the bot live within minutes and no operational overhead afterward, Hermify provisions a managed Hermes runtime, encrypts your Slack tokens at rest, exposes the allowlist in a UI instead of a .env, and keeps the Socket Mode connection healthy on a persistent server.

You bring the Slack workspace and a model provider key; the platform handles everything below. If you are evaluating that trade-off, the self-hosting vs managed comparison walks through the cost and maintenance numbers.