Skip to main content
Scout reads and posts in your Slack workspace and responds to DMs and @mentions as a teammate. Each Slack thread becomes its own session so follow-ups carry forward. The full setup, including the Slack app manifest and the complete scope list, lives in the Scout repo: SLACK_CONNECT.md.

​
Prerequisites

  • Scout running locally (setup) or deployed
  • A Slack workspace with admin privileges
  • ngrok (local development only)

​
Step 1: Give Slack a URL it can reach

Slack delivers events (DMs, mentions, channel messages) by POSTing to a URL. That URL has to be reachable from Slack’s servers. For local development, ngrok creates a public tunnel to a local port: 
ngrok http 8000
Copy the https://...ngrok-free.app URL. For production, use your deployed Railway URL.
Free ngrok URLs rotate on every restart. If you stop and restart ngrok, you’ll need to update the URL in your Slack app’s Event Subscriptions page.

​
Step 2: Register the Slack app from a manifest

A Slack app is configured by a JSON manifest that declares its identity, scopes, and the events it should receive. A manifest keeps scopes explicit and reproducible. The manifest requests the scopes Scout needs to read the workspace (search, channel and group history, IMs, user lookups) and to post replies. No admin scopes. The full list is in the manifest. Review it before installing. Copy the manifest from SLACK_CONNECT.md, paste into Slack’s Create New App → From a manifest flow, and replace the placeholder URL with your URL from Step 1.

​
Step 3: Install Scout into your workspace

Installing the App creates the bot identity in your workspace and issues the credentials Scout uses to authenticate every event and call. Two values to copy after install:
WhatWhere in SlackBecomes
Bot User OAuth TokenInstall App pageSLACK_BOT_TOKEN (xoxb-...)
Signing SecretBasic Information → App CredentialsSLACK_SIGNING_SECRET
The signing secret is what Slack uses to sign every incoming event. Scout verifies the signature on every request, which is how it knows the event actually came from Slack and not someone spoofing your endpoint.

​
Step 4: Wire credentials and restart

Add both values to .env: 
# .env
SLACK_BOT_TOKEN="xoxb-..."
SLACK_SIGNING_SECRET="..."
Restart: 
docker compose up -d

​
Verify

Find Scout under Apps in the Slack sidebar and DM it: 
hi
what contexts are registered?
Or invite it to a channel: 
/invite @Scout
@Scout look up the latest pricing for Anthropic's models.

​
Troubleshooting

The most common failure is “Your URL didn’t respond” during Slack’s verification challenge. That happens when Scout isn’t running at the moment Slack POSTs the challenge. Restart Scout, then retry from your Slack app’s Event Subscriptions page. If your ngrok URL has changed (free URLs rotate on restart), update the Request URL in Event Subscriptions and click Retry. If Scout doesn’t respond to mentions, check docker compose logs -f scout-api for signature verification errors. These usually mean the SLACK_SIGNING_SECRET in .env doesn’t match the one in your Slack app’s Basic Information page. For everything else, see SLACK_CONNECT.md.

​
How it works

Scout uses Agno’s Slack interface. Each Slack thread timestamp becomes an AgentOS session ID, so threads stay isolated and follow-ups in the same thread don’t need to re-mention @Scout. Scout maps Slack user IDs to display names, so it can address you by name. Setting SLACK_BOT_TOKEN also activates Slack as a context provider. Scout gets query_slack and update_slack tools, which work from any surface: the AgentOS UI, evals, Cron jobs, or Slack itself.

​
Next

Deploy to Railway →