How to set up Hermes Agent on Slack

What you need

Hermes connects to Slack through Socket Mode, an outbound WebSocket connection that stays open to receive events. You do not need a public URL or tunnel for this route.

• Hermes Agent installed with a model provider configured. Start with Hermes Agent messaging gateway explained if the gateway is new to you.
• A Slack workspace where you may create and install an app. Ask the workspace administrator if app installation is restricted.
• Two different secrets: a bot token beginning xoxb- and an app-level token beginning xapp-. You will also need your Slack Member ID.
• A computer that stays on and connected whenever you want the bot to answer.

Create the Slack app

A manifest is a configuration file that declares the app permissions, events and commands. The official Hermes docs recommend generating one with Agent view for a new app:

Terminal

hermes slack manifest --agent-view --write

Open the generated slack-manifest.json in your Hermes home (~/.hermes/ on Linux, macOS and WSL). At Slack app management↗ (opens in a new tab), choose Create New App, then From an app manifest. Select your workspace, paste the JSON, review the requested configuration and create the app. Slack manifest instructions↗ (opens in a new tab) describe this flow.

The Hermes manifest supplies the scopes, event subscriptions and slash commands. Continue with the token and Messages Tab checks below even when you use the manifest.

The manifest does not generate the app-level xapp- token; create it in the next step.

Get both tokens and enable messages

• In Settings → Socket Mode, confirm Enable Socket Mode is on. Under Settings → Basic Information → App-Level Tokens, create a token with connections:write. Copy its xapp- value for SLACK_APP_TOKEN.
• In Features → App Home → Show Tabs, enable Messages Tab and allow users to send slash commands and messages from that tab. Slack otherwise blocks DMs to the app.
• In Settings → Install App, choose Install to Workspace. Review the permissions and authorize the installation. Copy the Bot User OAuth Token beginning xoxb- for SLACK_BOT_TOKEN. Slack also exposes installation under OAuth & Permissions.
• Keep both tokens secret. Store them in your private profile configuration, never in a shared screenshot or Git repository. The Hermes docs recommend file permissions 600 on Unix and rotating tokens in Slack app settings.

Slack Socket Mode instructions↗ (opens in a new tab) confirm that the app-level token and bot token have different jobs. Do not substitute one for the other.

Choose who can talk to it

Find your own Member ID in Slack: open your full profile, open the more menu and choose Copy member ID. It looks like U01ABC2DEF3, rather than a display name. Repeat for each authorized person.

An allowlist is the list of people permitted to use the agent. Authorize only people you trust with its enabled tools and files. Keep GATEWAY_ALLOW_ALL_USERS unset or false and review existing global allowlists and pairing approvals, which can also grant access. Do not expect an unknown sender to receive a pairing code when an allowlist is set.

For a shared workspace, SLACK_ALLOWED_CHANNELS can also restrict conversations by channel ID. This is separate from sender authorization. The docs list IDs beginning C, G or D; inspect the channel details to get the actual ID. Keep your intended test conversation in the permitted set.

Connect it to Hermes

Run the setup wizard and select Slack. Supply the two tokens and allowed Member IDs. For manual configuration, the official docs give these environment variables.

The platform docs use ~/.hermes/.env for the default profile on Linux, macOS and WSL. Native Windows normally uses %LOCALAPPDATA%\hermes\.env. If you use a custom Hermes home or another profile, edit that profile's file instead. Replace every example value before starting.

Setup wizard

hermes gateway setup

Profile .env, manual alternative

SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3

Separate multiple allowed Member IDs with commas. Keep the tokens out of the public Slack channel. Restart an existing gateway after changing its credentials.

For scheduled delivery, the optional SLACK_HOME_CHANNEL holds the destination channel ID. Invite the bot there before using it. The channel name alone is not the ID.

Start the gateway and send your first message

Start in a terminal so you can read connection and authorization errors. Then open a DM with the installed app and send a short message such as Hello.

Foreground gateway

hermes gateway

In each Slack channel you want to use

/invite @Hermes Agent

Use your bot's name in the invitation. Hermes does not automatically join channels. After inviting it, send an @mention in that channel.

For an authorized sender, 1:1 DMs do not need a mention. Channels normally need an @mention to start a conversation. Follow-ups in a thread the bot has joined can continue without another mention. Group DMs use shared-conversation controls rather than the 1:1 DM exemption.

Confirm the response in Slack, then try a thread reply and a small non-sensitive attachment.

What it can do

• The official comparison table lists voice, images, files, threads, reactions, typing indicators and streaming updates for Slack.
• Incoming audio uses your configured speech-to-text provider. Text-to-speech replies arrive as audio file attachments. Voice requires the relevant speech services to be configured.
• Reading uploads needs files:read; uploading files needs files:write. Channel history and event subscriptions determine which messages reach the bot.
• Native streaming and custom working-state text depend on Slack app features and assistant:write. The docs describe fallback to edit-based updates when native streaming is unavailable.
• Messages from other bots are ignored by default. Keep that default for an initial setup. Enabling unrestricted bot replies can create loops.
• Reaction-triggered agent turns are optional and need additional scopes and events. A reaction appearing in Slack does not by itself mean it starts an agent task.

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

After your first message succeeds, stop the foreground gateway with Ctrl+C. For a normal host installation, the official gateway docs give these service commands:

Install, start and inspect the host service

hermes gateway install
hermes gateway start
hermes gateway status

Linux uses systemd, macOS uses launchd, and Windows uses a Scheduled Task at logon. On a headless Linux host using a user service, the docs give sudo loginctl enable-linger $USER to keep it available after logout. Windows Task Scheduler does not restart a gateway that crashes after its launcher exits.

In a container, use the documented container startup and restart policy instead of installing a host user service. For hosting choices, see How to run Hermes Agent 24/7 on a VPS or home server.

If it doesn't answer

• No DM reply: check message.im in Event Subscriptions, the Messages Tab setting, both tokens and your allowed Member ID. Read the gateway logs for invalid_auth or not_authed.
• DM works but channel messages do not: confirm the invitation, app_mention, message.channels and channels:history. Private channels also need message.groups and groups:history.
• Group DM is silent: check message.mpim, mpim:history and mpim:read, plus the shared-conversation mention and channel restrictions.
• Uploads cannot be read: check files:read. A successful text reply does not establish attachment access.
• After changing scopes or event subscriptions, reinstall the app to the workspace. Then restart the gateway if you changed its configuration.
• If the connection drops, inspect the computer's network connection. For more checks, see Hermes Agent bot not responding in your chat app.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes Slack docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• How to set up Hermes Agent on Microsoft Teams
• How to set up Hermes Agent on Google Chat
• How to set up Hermes Agent on Matrix
• Hermes Agent bot not responding in your chat app

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher