Hermes Agent Slack: Set Up The Socket Mode Bot In 6 Steps

Hermes Agent Slack setup comes down to two tokens, one allowlist line and a manifest that Hermes writes for you.

Below is the exact order I'd run it in, the five config lines I'd add before anyone else in the workspace sees the bot, and the two problems that catch most people.

Everything here comes from the official Hermes Slack setup page, pinned at release v0.23.1.

If you'd rather have my team plan how the bot fits into your business, book a free SEO strategy session and we'll map it with you.

Why Socket Mode Means No Public URL

Hermes talks to Slack over Socket Mode.

That's an outgoing WebSocket, so Slack never has to reach into your machine.

The docs say it runs behind firewalls, on your laptop or on a private server.

No webhook. No tunnel. No open port.

One warning before you start: Slack fully deprecated classic RTM apps in March 2025.

If you still have an old classic app lying around, don't reuse it. Build a fresh one with the steps below.

Step 1: Generate The Manifest Hermes Writes For You

Run this on the machine that will host the bot:

hermes slack manifest --agent-view --write

It saves ~/.hermes/slack-manifest.json and prints the paste-in steps.

That one file declares every built-in slash command, every OAuth scope, every event subscription, and switches Socket Mode on.

The --agent-view flag matters. New Slack apps must use Slack's Agent view, and once an app is on Agent view it can't go back to the older Assistant view.

Want a proper app description in Slack? Add --long-description-file AGENTS.md and Hermes copies that file in, as long as it sits between 175 and 4,000 characters.

Step 2: Create And Install The App From That Manifest

1. Open api.slack.com/apps and click Create New App.
2. Pick From an app manifest, choose your workspace, paste the JSON, then Next and Create.
3. Go to Settings → Install App → Install to Workspace and click Allow.
4. Copy the Bot User OAuth Token. It starts with xoxb-.

That token becomes SLACK_BOT_TOKEN.

Skipping the manifest is possible, but then you add 13 bot scopes, five event subscriptions and the Messages tab by hand. I wouldn't.

If you go manual anyway, the two scopes people forget are channels:history and groups:history. Without them the bot only ever works in DMs.

And switch on the Messages tab under Features → App Home, with the box that lets users send messages from it, or nobody can DM the bot at all.

Step 3: Make The xapp- Token With connections:write

Socket Mode needs a second, app-level token.

Open Settings → Basic Information → App-Level Tokens, name it something like hermes-socket, add the connections:write scope and click Generate.

The token starts with xapp- and becomes SLACK_APP_TOKEN.

If you built the app from scratch, toggle Settings → Socket Mode on first. Slack prompts you for this token right there.

🔥 Want the Agent OS with Hermes already wired into Slack? Inside the AI Profit Boardroom you get step-by-step video trainings on setups like this one, the installable Agent OS, four coaching calls a week and 3,400+ members swapping configs that work. → Join the AI Profit Boardroom

Step 4: Copy Your Member ID, Not Your Username

The allowlist uses Slack Member IDs.

Display names and usernames won't work.

Click your avatar, pick View full profile, open the ⋮ menu and choose Copy member ID.

It looks like U01ABC2DEF3.

Grab the ID for every teammate who should be able to talk to the bot.

Step 5: Fill In .env And Start The Gateway

Put the three required values in ~/.hermes/.env:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U01ABC2DEF3,U02XYZ4GHI5
SLACK_HOME_CHANNEL=C01234567890

The last line is optional. It's the channel where cron results and scheduled posts land.

Prefer prompts? hermes gateway setup walks you through the same values. Pick Slack when it asks.

Then start it:

hermes gateway                         # foreground, good for the first test
hermes gateway install                 # user service
sudo hermes gateway install --system   # Linux only, starts at boot

Run it in the foreground first so you can watch the log, then install the service once a DM gets an answer.

Lock the env file down too. The docs ask for permissions 600 on ~/.hermes/.env.

Running an agency that sits in several client workspaces? One gateway can join them all. Put one xoxb- token per workspace in SLACK_BOT_TOKEN, comma-separated, and keep a single xapp- token.

The first bot token in that list is the primary one, and it carries the Socket Mode connection.

Step 6: Invite The Bot Into Each Channel

The bot never joins channels on its own.

In every channel where you want it, type:

/invite @Hermes Agent

Private channels work the same way, but only after an invite.

Slack's scopes only let it read private channels it has been invited to.

How It Answers: DMs, Mentions And Threads

Know the default manners before you roll it out to the team.

• Direct messages: a 1:1 DM gets a reply to each message, tag or no tag.
• Channels: silence until someone @mentions it, then a reply in a thread under that message.
• Threads: once it's active in a thread, follow-up replies there don't need a mention.

Plain channel chatter without a mention gets ignored, which keeps busy channels quiet.

Each person also gets their own session in a shared channel, because group_sessions_per_user defaults to true.

Group DMs behave like channels, not like private chats. Mention rules and allowed_channels both apply there, so add a group DM's G… ID to free_response_channels if you want it to answer freely.

Flip it to false only if you want a whole channel to share one conversation, and remember one person's /reset then wipes it for everyone.

Commands In Threads Need The ! Prefix

Hermes registers its full command list with Slack as real slash commands: /btw, /stop, /new, /model, /help and the rest.

Type / and Slack's picker lists them with descriptions.

Slash replies are ephemeral, so only you see them and the channel stays clean.

The snag: Slack itself refuses slash commands inside thread replies.

Hermes gets round that with a ! prefix. Type !stop or !queue as an ordinary thread reply and it runs the same command.

When an approval prompt for a risky command can't show buttons, Hermes asks you to reply !approve or !deny instead.

After each hermes update, run hermes slack manifest --write again and paste the new file into Features → App Manifest → Edit, so new commands appear in Slack.

The Five Config Lines I'd Add First

These go in ~/.hermes/config.yaml. Each key is documented in the configuration options section.

slack:
  allowed_channels: ["C0123456789", "C0987654321"]
  ignore_other_user_mentions: true
  unauthorized_dm_behavior: "ignore"
display:
  platforms:
    slack:
      live_status: verb

1. allowed_channels makes the bot ignore every channel not on the list, even if someone mentions it there. 1:1 DMs stay open to allowlisted users.
2. ignore_other_user_mentions keeps it out of messages that open by tagging a colleague, like "@sam can you check this?".
3. unauthorized_dm_behavior: "ignore" drops DMs from people off the allowlist instead of offering them a pairing code. The default is pair.
4. live_status: verb shows "is running…" instead of the full command or file path, which the docs suggest for shared or customer-facing channels.
5. Leave allow_bots on its default "none" unless you run several bots. If you do, use "mentions". Two bots that answer everything will answer each other forever.

Worked Example: An Agency With One Channel Per Client

Say a small marketing agency keeps one Slack channel per client.

1. Invite the bot into #client-bakery and #client-gym, and add both IDs to allowed_channels.
2. Give each channel its own tone with channel_prompts, keyed by channel ID. The prompt is injected on every turn and never saved to the transcript.
3. Bind a skill per channel with channel_skill_bindings, so each new session there starts with the right playbook loaded.
4. An account manager mentions the bot under a client request and asks for three post ideas.
5. The bot replies in the thread. The team edits the ideas there and keeps going without re-mentioning it.

Write "draft only, a human sends it" into the channel prompt for anything client-facing.

The documented approvals cover risky commands, not the wording of a client post.

📞 Planning which jobs your Slack bot should own? Book a free SEO strategy session and my team will walk through your channels, your content and where an agent saves the most back-and-forth. → Grab a free call with my team

Worked Example: A Plumbing Office That Wants A Morning Board

Now a plumbing firm with an office manager and four engineers on Slack.

1. Set SLACK_HOME_CHANNEL to the ID of #jobs-today and invite the bot there.
2. Create a weekday cron job that reads the bookings list the office keeps in a shared file and writes a short job list.
3. Set its delivery to slack so it lands in the home channel, or to slack:U… to send it to the manager's DM.
4. Engineers reply in the thread with questions, and the bot answers there.
5. An engineer in the van sends the bot a voice message by DM. Hermes transcribes it before it answers, so a spoken "what's the access code for job four?" works.
6. Any message meant for a customer stays a draft for the office manager to send.

The Hermes cron docs cover the schedule side, and we went deep on it in our Hermes cron job walkthrough.

Want a thumbs-up to mean "approved"? Set reaction_triggers: true and a reaction on the bot's own messages becomes a turn for the agent. It needs the reactions:read scope and the reaction events, so regenerate the manifest first.

Delivery works even if cron runs apart from the gateway, because Hermes falls back to a plain Web API sender using the bot token.

When It Works In DMs But Not Channels

This is the number one setup issue in the docs.

Work down this list:

• Are message.channels and message.groups in your event subscriptions?
• Are the channels:history and groups:history scopes added?
• Did you reinstall the app after changing scopes or events? Slack ignores the change until you do.
• Is the bot invited to that channel?
• Did you actually @mention it?

Two more fixes from the troubleshooting table: if DMs say "Sending messages to this app has been turned off", switch on the Messages tab under App Home. If it can't read uploads, add files:read and reinstall.

Running It On Hermes Cloud Team Gateway

On a Hermes Cloud instance with Team Gateway switched on, Slack reaches your agent through a shared Hermes bot, not your own app.

The Telegram page explains this and names Slack and Discord alongside Telegram.

To run your own Slack app beside it, set GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS=true, but the instance then never sleeps.

On your own machine none of this applies. Since v0.23.0, one gateway per machine owns every session, so the Slack thread, the CLI and the Desktop all share one history.

The latest patch, v0.23.1, carries no Slack-specific notes, so nothing above changed in it.

Start with Step 1 today, test one DM, then invite it into a single channel before you widen the allowlist.

Also On Our Network

• 🌐 Four small-business Slack setups and the access rules owners must know
• 🌐 A nine-point scorecard of the Slack bot, with who should skip it
• 🌐 Five copy-paste prompts that let your agent set up Slack itself
• 🌐 Which benchmarked model to run behind each kind of Slack channel

FAQ: Hermes Agent Slack

Do I need a public URL or webhook for Hermes in Slack?

No. Hermes connects through Slack Socket Mode, an outgoing WebSocket, so it runs behind a firewall, on a laptop or on a private server.

Which two tokens does the Slack setup need?

A Bot User OAuth Token starting with xoxb- for SLACK_BOT_TOKEN, and an App-Level Token starting with xapp- with the connections:write scope for SLACK_APP_TOKEN.

Why does the bot ignore my channel messages?

In channels it only answers an @mention. If mentions fail too, check the message.channels and message.groups events and the history scopes, reinstall the app and invite the bot.

How do I run a Hermes command inside a Slack thread?

Slack blocks slash commands in threads, so type the command with a ! prefix instead, such as !stop or !queue, as a normal thread reply.

Can I switch an app back from Agent view to Assistant view?

No. The Hermes docs say Agent view cannot be reverted to Assistant view, and new Slack apps must use Agent view.

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

About Julian

I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.

I help business owners scale with AI agents, automation and SEO.

• I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
• I've grown a YouTube channel to 400,000+ subscribers.
• I wrote "Link Building Mastery".
• My Udemy courses have taught over 29,000 students.

→ Get my best AI training inside the AI Profit Boardroom

Get the tokens in, lock the allowlist, and if you want the full Agent OS around it, join the AI Profit Boardroom or book a free call with my team to plan your Hermes Agent Slack rollout.