# How to set up Hermes Agent on Slack

> Create a Slack app from the Hermes manifest, save both tokens, restrict access and start the gateway for DMs, channels and threads.

Canonical: https://hermeswatcher.com/learn/hermes-agent-slack-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## 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](https://hermeswatcher.com/learn/messaging-gateway-explained.md) 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](https://api.slack.com/apps), 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](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/) 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](https://docs.slack.dev/tools/python-slack-sdk/socket-mode/) 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](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md).

## 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](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md).

## Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

[Official Hermes Slack docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [How to set up Hermes Agent on Microsoft Teams](https://hermeswatcher.com/learn/hermes-agent-microsoft-teams-setup.md)
- [How to set up Hermes Agent on Google Chat](https://hermeswatcher.com/learn/hermes-agent-google-chat-setup.md)
- [How to set up Hermes Agent on Matrix](https://hermeswatcher.com/learn/hermes-agent-matrix-setup.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)

## Related tools

- [Slack: bring Hermes into your team workspace](https://hermeswatcher.com/tools/slack.md)
- [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)

## Sources

- [Hermes Agent: Slack](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack)
- [Slack: configure apps with manifests](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/)
- [Slack: Socket Mode client](https://docs.slack.dev/tools/python-slack-sdk/socket-mode/)
- [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Gateway authorization source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L660-L772)
- [Native Windows settings paths](https://hermes-agent.nousresearch.com/docs/user-guide/windows-native)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt