Local Development with Socket Mode
Copy page
Set up a personal Slack app for local development using Socket Mode — no tunnel required.
Local Development with Socket Mode
Socket Mode lets you receive Slack events over a WebSocket connection during local development — no tunnel (ngrok, Cloudflare Tunnel) needed.
Each developer should create their own personal Slack app with Socket Mode enabled. Socket Mode distributes events randomly across connected clients rather than broadcasting to all. Sharing an app means each developer receives roughly half the events.
Prerequisites
- A Slack workspace where you can install apps (workspace admin or create-app permissions)
- The monorepo set up:
pnpm install ENVIRONMENT=developmentset in your.envfile — Socket Mode only starts in development
Quick setup (recommended)
Run the guided setup script from the monorepo root:
The script walks through four steps automatically:
- Config token — Opens api.slack.com/apps and prompts for your Slack App Configuration refresh token (one-time paste)
- Create app — Creates a personal Slack app named
Inkeep Dev <random-id>(e.g.Inkeep Dev frost-ember) using the canonical manifest - App-Level Token — Prompts you to generate a
connections:writetoken in your app settings (the only manual step — Slack provides no API for this) - OAuth install — Starts a temporary local server, opens the browser, and completes the OAuth flow automatically
All credentials are written to your .env file. State is saved to .slack-dev.json (git-ignored) so subsequent runs require zero pastes.
| Run | Pastes required |
|---|---|
| First run | 2 (refresh token + app-level token) |
| Re-runs | 0 |
To start fresh (e.g. if you deleted your app), remove .slack-dev.json and re-run the script.
Manual setup
If you prefer to configure things yourself:
Create a dev Slack app
Go to api.slack.com/apps → Create New App → From an app manifest.
Use packages/agents-work-apps/src/slack/slack-app-manifest.json as your starting point. Make these changes:
- Set
settings.socket_mode_enabledtotrue - Remove all
request_urlandurlfields fromevent_subscriptions,interactivity, and slash commands - Rename the app (e.g.
Inkeep Dev - YourName)
Generate an App-Level Token
In your app settings → Basic Information → App-Level Tokens:
- Click Generate Token and Scopes
- Name:
socket-mode, Scope:connections:write - Copy the token (starts with
xapp-)
Install the app
Go to Install App → Install to Workspace and authorize. Copy the Bot User OAuth Token (starts with xoxb-).
Verify it works
- Start the dev server:
- Look for the log message:
Slack Socket Mode client started - In your Slack workspace,
@mentionyour dev bot in a channel — the event should be received and processed locally
If the bot hasn't been added to a channel yet, invite it first: /invite @inkeep-your-dev-id
How it works
Socket Mode and the production HTTP path share the same event dispatcher and handlers — only the transport differs:
The Socket Mode adapter:
- Receives pre-parsed events over WebSocket (no signature verification needed — the connection is authenticated)
- Calls
ack()immediately instead of returning an HTTP 200 - Routes events through the same
dispatchSlackEvent()function used by the HTTP path - Creates OTel tracing spans with identical span names and attributes