How to Integrate Hermes Agent With Slack for Team AI Automation

Nous Research Hermes Agent is an open-source (MIT-licensed) AI agent that runs on your own server, remembers what it learns, and builds reusable skills from past conversations. The messaging gateway is a single background process that connects Hermes to over 20 platforms, including Slack, Telegram, Discord, WhatsApp, Microsoft Teams, and Matrix. It handles sessions, runs scheduled automations, and delivers voice messages across all configured platforms simultaneously.

Slack gets full feature support: file attachments, threaded replies, emoji reactions, typing indicators, streaming responses, and voice transcription. When someone @mentions the bot in a channel, Hermes replies in a thread. In DMs, it responds to every message without needing a mention. The agent's persistent memory means it builds context over time. Ask it to research a topic on Monday, and it still remembers the findings on Friday.

The integration runs through Slack's Socket Mode, which means no public URL or webhook endpoint is required. Your Hermes instance connects outbound to Slack's API over a WebSocket, reducing the attack surface compared to HTTP-based bot architectures. For teams already running Hermes locally or in Docker, adding Slack takes about ten minutes.

Hermes includes a manifest generator that handles all the scope and event configuration automatically. This is the fast path.

Generate the App Manifest

Run the manifest command from your Hermes installation:

hermes slack manifest --write

This produces a JSON manifest with every required scope, event subscription, and slash command pre-configured. Open api.slack.com/apps, click "Create New App," select "From an app manifest," paste the generated manifest, and follow the prompts.

Required Bot Token Scopes

If you prefer manual setup, add these scopes under OAuth & Permissions:

• chat:write for sending messages
• app_mentions:read for detecting @mentions
• channels:history and channels:read for public channel access
• groups:history for private channel access
• im:history, im:read, and im:write for direct messages
• users:read for looking up user information
• files:read and files:write for attachment handling

Enable Socket Mode

Navigate to Settings > Socket Mode and toggle it on. Create an app-level token with the connections:write scope. This token starts with xapp- and is separate from the bot token.

Subscribe to Events

Under

Features > Event Subscriptions, add these bot events:

• message.im (required for DMs)
• message.channels (required for public channels)
• message.groups (recommended for private channels)
• app_mention (required to prevent SDK errors)

Missing event subscriptions are the most common cause of "the bot works in DMs but ignores channels." If you skip message.channels, Slack never delivers public channel messages to the gateway.

Install and Collect Tokens

Go to Settings > Install App, click "Install to Workspace," and authorize. Copy the Bot User OAuth Token (starts with xoxb-). You now have two tokens: the xapp- app token from Socket Mode and the xoxb- bot token from the installation.

With the Slack app created, point the Hermes gateway at it.

Interactive Setup

The guided wizard is the simplest approach:

hermes gateway setup

Select Slack when prompted, paste your bot and app tokens, and enter the Slack Member IDs of authorized users. The wizard writes everything to ~/.hermes/.env and offers to start the gateway when finished.

Manual Configuration

For manual setup, add these environment variables to ~/.hermes/.env:

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

The SLACK_ALLOWED_USERS setting is a security requirement. Without it, Hermes denies all messages by default. Find Member IDs by clicking a user's profile in Slack, selecting "View full profile," then the overflow menu (three dots), and "Copy member ID."

Set a home channel for scheduled messages and cron output:

SLACK_HOME_CHANNEL=C01YOURCHANNEL

Start the Gateway

hermes gateway start

The gateway runs as a background service. Check its status with hermes gateway status and view logs for connection confirmation. Once running, invite the bot to a channel with /invite @Hermes Agent and send a test message by @mentioning it.

Persist Hermes Agent Files Across Slack Sessions

Free 50 GB workspace with MCP server access. Your agent uploads files from Slack, your team browses them in the browser. No credit card required.

Start 14-Day Trial

A single Hermes instance can behave differently in each channel. You control this through ~/.hermes/config.yaml.

Mention and Reply Behavior By default, Hermes requires an @mention in channels but responds to all DMs:

slack:
  require_mention: true
  mention_patterns:
    - "hey hermes"
    - "hermes,"
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

The mention_patterns list lets team members trigger Hermes with casual phrasing instead of a formal @mention. Setting reply_in_thread: true keeps conversations tidy by containing all responses in threads rather than flooding the main channel.

Channel-Specific Prompts

Different channels can give Hermes different instructions:

channel_prompts:
  "C01RESEARCH": |
    You are a research assistant. Focus on finding academic
    sources and summarizing papers.
  "C02ENGINEERING": |
    You are a code review assistant. When asked about code,
    focus on correctness, performance, and security.

Skill Bindings

Bind specific Hermes skills to channels so the agent loads the right tools automatically:

channel_skill_bindings:
  - id: "C01RESEARCH"
    skills:
      - arxiv
      - writing-plans
  - id: "C03SALES"
    skills:
      - crm-lookup

This means the research channel gets access to academic search tools, while the sales channel loads CRM-related skills. Skills are part of Hermes Agent's self-improving system: the agent generates new skills from solved problems and reuses them in future conversations.

Multi-Workspace Deployments

For organizations with multiple Slack workspaces, a single gateway instance can serve all of them. Provide comma-separated bot tokens:

SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token

Each workspace authenticates independently and gets its own bot user ID. The gateway routes messages to the correct workspace-specific client automatically.

Hermes can generate files, receive attachments, and send documents through Slack. But those files live on the host machine's filesystem. If the container restarts or the disk fills up, files disappear. And sharing files with someone who is not in Slack requires manual transfer.

You can solve this with local filesystem mounts, an S3 bucket, or a shared cloud drive. Each works, but each also requires extra configuration for access control, team sharing, and search.

Fastio workspaces offer a cleaner option for teams that want files to be searchable, shareable, and accessible to both agents and humans through the same interface. Create a free workspace (50 GB storage, no credit card) and connect it through the Fastio MCP server. When Hermes generates a report in Slack, it can upload the output to a shared workspace where team members browse files through Fastio's web UI, search by content using Intelligence Mode, or pull files into their own tools.

The Fastio MCP server exposes workspace operations, file uploads, downloads, and AI queries as tool calls. Hermes can read from and write to workspaces during any conversation, whether triggered from Slack, Telegram, or the CLI. Files persist across sessions and across platforms, so a document uploaded from a Slack conversation is immediately available in every other Hermes session.

For teams running multiple agents, Fastio's file locks prevent conflicts when two agents try to write the same file simultaneously. Audit trails track every file operation, giving you visibility into what the agent created, modified, or shared. When the agent finishes a project, ownership transfer lets you hand the entire workspace to a human account while the agent retains admin access for ongoing maintenance.

Most Slack integration problems come from missing event subscriptions or permission scopes. Here are the issues teams hit most often, along with fixes.

Bot responds in DMs but ignores channels. This almost always means message.channels (public) or message.groups (private) events are not subscribed. Add them under Features > Event Subscriptions, then reinstall the app. Scope and event changes do not take effect until you reinstall.

Bot does not appear in DMs. Enable the Messages Tab under Features > App Home and check "Allow users to send Slash commands and messages from the messages tab."

File attachments are not readable. Add the files:read scope under OAuth & Permissions and reinstall. Without this scope, the gateway receives file metadata but cannot download the actual content.

Slash commands fail in threads. Slack blocks native slash commands inside thread replies. Use the ! prefix instead (!stop, !new, !queue) when working within a thread.

Voice messages are not transcribed. Verify that speech-to-text is enabled in ~/.hermes/config.yaml with stt_enabled: true. Hermes supports local faster-whisper, Groq Whisper (requires GROQ_API_KEY), or OpenAI Whisper (requires VOICE_TOOLS_OPENAI_KEY).

Token errors on startup. Regenerate both tokens in the Slack app settings. The bot token (xoxb-) comes from Settings > Install App, and the app token (xapp-) comes from Settings > Basic Information > App-Level Tokens. Update ~/.hermes/.env with the new values.

Security best practice. Store tokens in ~/.hermes/.env with file permissions set to 600. Always populate SLACK_ALLOWED_USERS before exposing the bot to any channel. Without this setting, Hermes denies all incoming messages as a safety default.