:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Slack local setup guide
How to point a real Slack workspace at your local PostHog so you can test the PostHog Desktop
coding agent (@PostHog <task> → sandbox run) end to end. The same tunnel + workspace works for
the other Slack integrations too, but this guide only documents what we verified.
Slack is SaaS-only: there's no self-hosted Slack. So "local testing" means a real (throwaway) Slack workspace + app whose webhooks and OAuth callback reach your laptop through a tunnel. This guide captures a setup that has been verified end to end.
Prerequisite: the PostHog Desktop stack must already work locally — GitHub App, temporal worker, sandboxes. If you haven't done that yet, follow sandboxes-setup-guide.md first and come back here.
How requests flow
Understanding this makes the two non-obvious config steps (ngrok host_header and
SITE_URL) self-explanatory.
Slack ──HTTPS──▶ ngrok edge ──▶ ngrok agent (laptop) ──▶ Caddy :8010 ──▶ Django :8000
(events, (dev proxy) (web)
interactivity,
OAuth callback)
- Everything Slack needs — the event webhook, the interactivity callback, the OAuth
redirect, and the PostHog UI — is served by Caddy on port 8010 (the dev proxy that
hogli startruns). Port 8000 is Django direct and does not serve the frontend. - The dev Caddy only answers for the
localhosthost (${CADDY_HOST:-http://localhost:8000}indocker-compose.dev.yml). A request arriving withHost: <you>.ngrok.devfalls through to nothing and you get200 OKwith an empty body. That's why the tunnel must rewrite the Host header tolocalhost(Step 1). - The OAuth
redirect_uriis built server-side fromSITE_URL, not from the browser address bar (OauthIntegration.redirect_uri()inposthog/models/integration/oauth.py), and it force-upgrades the scheme to https —SITE_URL.replace('http://', 'https://').SITE_URLdefaults tohttp://localhost:8010(posthog/settings/__init__.py:69), so at that default Slack is handedhttps://localhost:8010/...— which has no TLS, hence the browser SSL error. Point it at your tunnel for the OAuth step (Step 3).
Step 1 — ngrok tunnel into Caddy
You need a stable public HTTPS URL. Slack lists ngrok as its preferred tunnel, so that's what
this guide uses (a Hobbyist plan covers a few reserved domains) — but any HTTPS tunnel works.
Cloudflare Tunnel (cloudflared) is a fine free alternative; whatever you pick, point it at
8010 (Caddy) and make it rewrite the upstream Host header to localhost (see "How requests
flow" for why).
Reserve an ngrok domain, then authenticate once:
ngrok config add-authtoken <your-ngrok-authtoken>
Set the reserved URL in .env.local:
SITE_URL=https://<you>-posthog.ngrok.dev
hogli start detects an ngrok SITE_URL and starts the tunnel for you. It creates a temporary ngrok configuration that forwards to 8010 and rewrites the upstream Host header to localhost.
Verify the tunnel reaches Django through Caddy:
curl -sS https://<you>-posthog.ngrok.dev/_preflight | jq .
You want real JSON back (the response header is server: granian). If you get an empty
body with server: Caddy, the host_header rewrite is missing or the domain isn't
actually bound — fix that before continuing.
Modal sandboxes: this single Caddy tunnel is enough for Slack. Modal sandboxes reach PostHog over the public URL and work fine through Caddy, so you do not need a separate
:8000tunnel for the Slack flow. If you're also testing Modal sandboxes, keep your existinggateway(3308) andmcp(8787) tunnels — they're independent of this one. See the sandbox guide.
Step 2 — create the Slack app
- Create a throwaway Slack workspace (e.g.
posthog-slack-dev-<you>). You need admin to install apps. - api.slack.com/apps → Create New App → From an app manifest → pick your workspace → paste the manifest below (swap in your domain):
display_information:
name: posthog-slack-dev
features:
bot_user:
display_name: posthog-slack-dev
always_online: true
app_home:
home_tab_enabled: true
messages_tab_enabled: true
messages_tab_read_only_enabled: false
oauth_config:
redirect_urls:
- https://<you>-posthog.ngrok.dev/integrations/slack/callback
- https://<you>-posthog.ngrok.dev/complete/slack-link/
scopes:
bot:
- app_mentions:read
- channels:read
- groups:read
- channels:history
- groups:history
- chat:write
- canvases:write
- files:write
- reactions:read
- reactions:write
- users:read
- users:read.email
user:
- openid
- email
- profile
- canvases:read
settings:
event_subscriptions:
request_url: https://<you>-posthog.ngrok.dev/slack/event-callback
bot_events:
- app_mention
- app_home_opened
- message.channels
- reaction_added
interactivity:
is_enabled: true
request_url: https://<you>-posthog.ngrok.dev/slack/interactivity-callback
org_deploy_enabled: false
socket_mode_enabled: false
When you click Create, Slack verifies the event URL with a synchronous challenge POST, so
Django must be up at that moment.
- From Basic Information, copy the Client ID, Client Secret, and Signing Secret.
link_sharedis left out on purpose — it needs thelinks:readscope (the manifest won't save otherwise) and the coding agent doesn't use it.
The
app_homeblock +app_home_openedbot event power the App Home tab. With theslack-app-onboardingflag on, the same event, an install, a reinstall, ateam_joinand a person's first@PostHogmention start theslack-app-onboardingTemporal workflow, which posts a person's onboarding thread in the PostHog DM once. It needs the Temporal worker running. The thread checks each step again before it shows it, so a person who already linked their account or chose a model sees that step as already set. To see the thread again in a dev workspace, clear theonboardingfield of your row inslack_app_slacksettings. The Sign in with Slack (OpenID Connect) flow needsuserscopesopenid+profileand the second redirect URL (/complete/slack-link/). Drop those if you don't want either feature locally. Neither is behind a feature flag: the App Home tab renders for every install, and the identity link appears only when the install holds theusers:readandusers:read.emailscopes.
The
canvases:readuser scope lets the Slack MCP connection read canvases that the authorizing user can access.
reaction_added+reactions:readpower thumbs-reaction feedback on agent replies. Without them a 👍/👎 reaction on a reply records nothing, again with no error.
message.channelsis what makes Slack deliver plain channel messages. Without it you getapp_mentiononly, so@PostHogworks and everything driven by an untagged message — workflow Slack triggers, untagged thread follow-ups — receives nothing. There is no error: Slack simply never sends the event, so the ngrok inspector stays empty too.
Step 3 — backend credentials and SITE_URL
PostHog Desktop reuses the regular Slack notifications app, so set the standard
SLACK_APP_* credentials in .env and restart the django +
temporal-django-worker processes so it reloads. These are dynamic settings
seeded from the env on boot (posthog/settings/dynamic_settings.py):
SLACK_APP_CLIENT_ID=<client id>
SLACK_APP_CLIENT_SECRET=<client secret>
SLACK_APP_SIGNING_SECRET=<signing secret>
Confirm the backend picked them up:
curl -sS https://<you>-posthog.ngrok.dev/_preflight | jq '.slack_service'
# => { "available": true, "client_id": "...." }
SITE_URL must point at your tunnel for the OAuth step (Step 5), or the redirect goes to
https://localhost:8010/... and the browser fails with an SSL error. Put it in .env.local so
it is available every time you run hogli start.
A tunnel
SITE_URLbreaks local sandbox agents. It reaches the sandbox asPOSTHOG_API_URL, andgetCloudTaskGatewayUrlmaps onlylocalhostandhost.docker.internalto the local LLM gateway on 3308. Every other host falls through to the production gateway, where a local run token does not authenticate. The agent starts, sends its first prompt, and hangs until its inactivity window ends, with nothing in any log. SetSANDBOX_LLM_GATEWAY_URL=http://host.docker.internal:3308alongside the tunnelSITE_URL, or keepSITE_URLon localhost and hand-write the integration row (Step 5).
There's also an
NGROK_URLenv var thatredirect_uri()checks beforeSITE_URLin DEBUG — it would override just the OAuth redirect and leaveSITE_URLalone. We usedSITE_URLand didn't exercise theNGROK_URLpath, so treat it as untested.
Step 4 — feature flags
One flag gates the UI: tasks (shows the Tasks scene and gates task creation —
products/tasks/backend/access.py). It's an active flag in
frontend/src/lib/constants.tsx, so the normal local sync enables it at 100%:
python manage.py sync_feature_flags
If you already sync flags the usual way locally, it's likely on already — nothing to do.
(setup_background_agents also turns on tasks as part of the sandbox setup.) The
Slack mention webhook itself is not flag-gated — once the slack integration is
connected, @PostHog events reach the agent unconditionally.
Step 5 — connect the integrations
Slack. PostHog Desktop piggybacks on the regular Slack notifications install — there's no
separate "PostHog Desktop Slack" install anymore. Go to Settings → Project → Integrations,
find Slack, click Connect to Slack, and authorize in your dev workspace. The PostHog Desktop
agent reads the same Integration row that the notifications product writes. Verify:
python manage.py shell -c "from posthog.models.integration import Integration; \
print(list(Integration.objects.filter(kind='slack').values('id','team_id','integration_id')))"
# => [{'id': ..., 'team_id': 1, 'integration_id': 'T0........'}]
The tasks flag from Step 4 still gates the Tasks UI on top of the connected integration.
The connect cannot complete against the Vite dev server.
redirect_uriis built fromSITE_URL(OauthIntegration.redirect_uri()), so Slack returns you to the tunnel origin, and/integrations/:kind/callbackis a frontend route rather than a Django view. The dev SPA loads its modules fromhttp://localhost:8234, which an https page may not fetch, so the callback page never renders and the flow stops there. Serve a built frontend if you need the real OAuth round-trip. To skip it, install the app to your workspace in the Slack console and write the row from the bot token instead — but note that a hand-written row has noconfig["authed_user"], and the channel picker reads that field, so channel lists fail until you add it.
GitHub (Settings → Integrations): connect a team GitHub with at least one repo (otherwise the repo cascade has nothing to pick and creates a no-repo task), and connect your personal GitHub under User → Personal integrations (otherwise the task parks behind a "Connect GitHub" button before the agent runs).
Step 6 — Slack user → PostHog user
resolve_slack_user matches your Slack profile email to a PostHog org member. Locally this is
handled for you: a DEBUG branch (products/slack_app/backend/api.py:417-419) forces the email
to [email protected], which is the default local dev user — so resolution works out of the box.
If your local user has a different email, point that branch (or your user's email) at it.
Step 7 — smoke test
In a channel in your dev workspace:
/invite @posthog-slack-dev
@posthog-slack-dev add a comment to the README explaining how to run tests
(The real @-handle is whatever Slack assigned — type @p and let autocomplete confirm.)
A successful run reacts 🌱 :seedling: on your message and posts a threaded "Working on task… ⏳"
with a footer whose View session link opens the task — that's what we saw. You may also see 🔍 :mag: first, but only
when the repo-discovery agent has to choose among repos (a no-repo prompt skips it, as ours did).
Follow-ups — reply in-thread with another @mention — are forwarded to the running sandbox and
should react 👀 → 🦔 (or ❌ if the sandbox is gone). Expected from the code; not verified in our run.
Use a development Slack app from production Desktop
This setup lets selected projects connect to Slack through the MCP store with a development Slack app. It does not move bot events to production or change the production Slack app's credentials.
- Add
https://us.posthog.com/api/mcp_store/oauth_redirect/to the development app's OAuth redirect URLs for US production. Keep its existing dev redirect URLs and event callbacks. For another region, use that region's PostHog origin instead. - Provision the existing development app's client ID and client secret as the
SLACK_DEV_APP_CLIENT_IDandSLACK_DEV_APP_CLIENT_SECRETinstance settings in the target region. Do not replaceSLACK_APP_CLIENT_ID,SLACK_APP_CLIENT_SECRET, orSLACK_APP_SIGNING_SECRET. - Set
MCP_STORE_SLACK_DEV_ALLOWED_TEAM_IDSto a comma-separated list of permitted project IDs in that region's server configuration. The default is empty, which blocks access. Use*to permit all projects in the region, for example on the dev region where every user is internal. Do not use*in a production region. Apply the same configuration to the web processes and workers. Production deployments must also add these variables toposthog/chartsand provision their values throughposthog/secrets. Adding the settings in this repository does not configure production. - Enable the
mcp-slack-devfeature flag for PostHog users. Target users whose email ends with@posthog.com. Use that email condition, not a cohort or an early access list. The check evaluates the flag locally and treats targeting it cannot resolve as off. For local testing, addmcp-slack-devtoPOSTHOG_FEATURE_FLAGS_FORCE_ENABLEDand restart Django. - Run
python manage.py sync_mcp_server_templatesin that environment. The existing Slack MCP entry becomes Slack via PostHog (dev) and uses the separate credentials. It activates only after the shared-client probe passes. Existing Slack MCP installations block a change of OAuth app; do not disconnect them without their owners' approval. - In an allowed project, connect Slack via PostHog (dev) from the MCP store, finish Slack authorization, and confirm that a channel search returns results and an accessible canvas can be read. Confirm that another project cannot list or authorize this entry.
Reconnect an installation that was authorized before a new reviewed scope was synced. Existing OAuth tokens do not gain the new scope automatically.
The connection keeps the catalog's reviewed MCP scopes; it does not request all scopes available to the bot. The project restriction applies to authorization, token exchange, token refresh, and upstream requests. Removing a project from the allowlist blocks its existing connection, even before catalog sync runs.
To retire this setup, empty the allowlist and run catalog sync to deactivate the entry.
Disconnect the development-app MCP installations, then run catalog sync again to restore the slack_app credential source.
Remove the separate development credentials and the added production redirect URL if nothing else uses them.
After the production catalog suspension is removed, run catalog sync and reconnect through the production app.
Tokens from the development app cannot be transferred to the production app.
Debugging
- ngrok request inspector (
http://127.0.0.1:4040) — confirms Slack's webhook actually reached you and shows the response. A202here means the event arrived and the problem is downstream; this is how we confirmed delivery during setup. - Temporal Web (
http://localhost:8233, filter workflow typeslack-app-mention-processing) — shows which activity the run reached. The happy path ends atcreate_posthog_code_task_for_repo_activity. - Going deeper, the
django/temporal-django-workerlogs carryposthog_code_*structlog lines, and Slack's app Event Deliveries page shows delivery failures — neither was needed in our run, but they're there if you get stuck.
Channel search cache
Channel name search uses the cached channel list. If name search does not find a channel, paste its ID to look it up directly in Slack. A successful ID lookup also adds the channel to an existing search cache with the same access scope. Concurrent ID lookups keep both channels in the cache. The update keeps the cache refresh time and expiry. It does not load other missing channels or create a channel list from a single lookup.
Troubleshooting
Channel selection
Paste a Slack channel ID into the channel picker to select that channel. The picker shows the channel name when the lookup succeeds, without requiring you to click outside the input. Click the selected channel in the list to clear the search text.
The walls we actually hit and fixed:
| Symptom | Cause / fix |
|---|---|
curl /_preflight returns 200 with an empty body, server: Caddy |
The tunnel reaches Caddy but isn't sending Host: localhost, so Caddy doesn't match its site block. Add host_header: localhost to the tunnel. |
OAuth → browser ERR_SSL_PROTOCOL_ERROR on localhost:8010 |
SITE_URL is still the localhost default. Point it at your https tunnel and restart django (Step 3). |
| OAuth → "redirect_uri did not match any configured URIs" | The Slack app's Redirect URLs must include https://<tunnel>/integrations/slack/callback — add it and click Save URLs. |
| Manifest won't save: "link_shared is missing scope links:read" | Remove link_shared from bot_events (Step 2). |