Skip to content

: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.

18.7 KB
Raw Blame

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 start runs). Port 8000 is Django direct and does not serve the frontend.
  • The dev Caddy only answers for the localhost host (${CADDY_HOST:-http://localhost:8000} in docker-compose.dev.yml). A request arriving with Host: <you>.ngrok.dev falls through to nothing and you get 200 OK with an empty body. That's why the tunnel must rewrite the Host header to localhost (Step 1).
  • The OAuth redirect_uri is built server-side from SITE_URL, not from the browser address bar (OauthIntegration.redirect_uri() in posthog/models/integration/oauth.py), and it force-upgrades the scheme to https — SITE_URL.replace('http://', 'https://'). SITE_URL defaults to http://localhost:8010 (posthog/settings/__init__.py:69), so at that default Slack is handed https://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 :8000 tunnel for the Slack flow. If you're also testing Modal sandboxes, keep your existing gateway (3308) and mcp (8787) tunnels — they're independent of this one. See the sandbox guide.

Step 2 — create the Slack app

  1. Create a throwaway Slack workspace (e.g. posthog-slack-dev-<you>). You need admin to install apps.
  2. 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.

  1. From Basic Information, copy the Client ID, Client Secret, and Signing Secret.

link_shared is left out on purpose — it needs the links:read scope (the manifest won't save otherwise) and the coding agent doesn't use it.

The app_home block + app_home_opened bot event power the App Home tab. With the slack-app-onboarding flag on, the same event, an install, a reinstall, a team_join and a person's first @PostHog mention start the slack-app-onboarding Temporal 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 the onboarding field of your row in slack_app_slacksettings. The Sign in with Slack (OpenID Connect) flow needs user scopes openid + email + profile and 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 the users:read and users:read.email scopes.

The canvases:read user scope lets the Slack MCP connection read canvases that the authorizing user can access.

reaction_added + reactions:read power thumbs-reaction feedback on agent replies. Without them a 👍/👎 reaction on a reply records nothing, again with no error.

message.channels is what makes Slack deliver plain channel messages. Without it you get app_mention only, so @PostHog works 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_URL breaks local sandbox agents. It reaches the sandbox as POSTHOG_API_URL, and getCloudTaskGatewayUrl maps only localhost and host.docker.internal to 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. Set SANDBOX_LLM_GATEWAY_URL=http://host.docker.internal:3308 alongside the tunnel SITE_URL, or keep SITE_URL on localhost and hand-write the integration row (Step 5).

There's also an NGROK_URL env var that redirect_uri() checks before SITE_URL in DEBUG — it would override just the OAuth redirect and leave SITE_URL alone. We used SITE_URL and didn't exercise the NGROK_URL path, 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_uri is built from SITE_URL (OauthIntegration.redirect_uri()), so Slack returns you to the tunnel origin, and /integrations/:kind/callback is a frontend route rather than a Django view. The dev SPA loads its modules from http://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 no config["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.

  1. 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.
  2. Provision the existing development app's client ID and client secret as the SLACK_DEV_APP_CLIENT_ID and SLACK_DEV_APP_CLIENT_SECRET instance settings in the target region. Do not replace SLACK_APP_CLIENT_ID, SLACK_APP_CLIENT_SECRET, or SLACK_APP_SIGNING_SECRET.
  3. Set MCP_STORE_SLACK_DEV_ALLOWED_TEAM_IDS to 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 to posthog/charts and provision their values through posthog/secrets. Adding the settings in this repository does not configure production.
  4. Enable the mcp-slack-dev feature 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, add mcp-slack-dev to POSTHOG_FEATURE_FLAGS_FORCE_ENABLED and restart Django.
  5. Run python manage.py sync_mcp_server_templates in 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.
  6. 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. A 202 here means the event arrived and the problem is downstream; this is how we confirmed delivery during setup.
  • Temporal Web (http://localhost:8233, filter workflow type slack-app-mention-processing) — shows which activity the run reached. The happy path ends at create_posthog_code_task_for_repo_activity.
  • Going deeper, the django / temporal-django-worker logs carry posthog_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).