: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.
@posthog/web
Browser host for PostHog Desktop. Boots the same @posthog/ui shell and
@posthog/core services as the desktop app, with web platform adapters —
no Electron, no local workspace-server. Scope today: auth + cloud tasks
(local workspaces, terminal, and local git need a workspace backend and are
out of scope for the web host's first iteration).
Run
pnpm --filter @posthog/web dev # Vite on http://localhost:5273
No separate backend process: the host router slice runs in the browser
(web-host-router.ts), served over tRPC's unstable_localLink
(web-trpc.ts). auth, cloudTask, and analytics are the real routers
backed by in-browser AuthService / CloudTaskService (both are
host-agnostic core code); the rest are stubs that return benign empties.
Procedures outside the slice fail with NOT_FOUND at call time — that is the
to-do list for widening the web surface.
Testing
pnpm --filter @posthog/web test:e2e # Playwright: happy-path browser e2e
tests/e2e/drives stock Chromium against the Vite dev server (Playwright starts it). Scope is the hermetic happy path up to the OAuth wall — boot, container wiring, onboarding → sign-in card, and the/callbackrelay — since real login needs PostHog cloud and a popup IdP. Runs in CI (test.yml), reusing the desktop suite's cached Chromium.- The boot spec doubles as the host-capability guard:
web-container.tsrunsassertHostCapabilities(REQUIRED_HOST_CAPABILITIES)at container load, so an unbound capability throws before the app mounts and fails the boot spec. (A jsdom unit test that imported the whole composition root was tried but dropped — evaluating the entire app graph took ~30s+ per run, and the e2e already covers it.) The capability mechanism is unit-tested in@posthog/di(hostCapabilities.test.ts).
Auth
WebOAuthFlowService (web-oauth-flow.ts) implements the core
IAuthOAuthFlowService with a browser PKCE flow: popup to
{cloud}/oauth/authorize, redirect back to {origin}/callback, code relayed
to the opener tab over a BroadcastChannel, token exchange via fetch. Session
persistence is localStorage (web-auth-adapters.ts); the refresh token is
encrypted at rest with AES-GCM under a non-extractable Web Crypto key held
in IndexedDB (webAuthTokenCipher). The key round-trips through structured
clone but its raw bytes are never exposed to JS, so a stolen localStorage dump
can't be decrypted offline — matching the bar the desktop host's machine-bound
cipher sets. A live XSS payload can still ask the key to decrypt while it runs
on the page (httpOnly cookies would need server-side sessions the cloud host
doesn't have). Tokens written by the earlier plaintext build fail to decrypt
and are cleared, forcing a clean re-auth.
Hosting
Build a static bundle and serve it:
pnpm --filter @posthog/web build # Vite output: apps/web/dist
Serve dist/ as a single-page app with a fallback to index.html for unknown
paths. The OAuth popup lands on the real path /callback (OAUTH_CALLBACK_PATH
in web-oauth-flow.ts, dispatched in main.tsx), which must load the SPA to
relay the code back to the opener tab. The app's own routes use hash history, so
/callback is the only real path that needs the fallback.
The build is code-split: vendor libraries into cacheable groups (manualChunks
in vite.config.ts) and each route's component into its own lazy chunk (the
TanStack Router plugin's autoCodeSplitting, mirroring apps/code), so a screen
downloads only when navigated to. All emitted assets are content-hashed — serve
dist/assets/ with a long-lived immutable Cache-Control and only index.html
short-lived, so returning users re-download just the chunks that changed.
The steps below are one-time setup for a deployed origin. None block the app from booting, but auth, attachments, and integrations each need one.
Environment variables
All are Vite build-time vars (import.meta.env.*), baked in at build time.
| Var | Required | Purpose |
|---|---|---|
VITE_POSTHOG_API_KEY |
Recommended | Real phc_… project key. Enables posthog-js analytics, error/rejection capture, session recording, and real feature flags. The guard in main.tsx requires the phc_ prefix; without it posthog stays uninitialized, the tracker/analytics service no-op and every flag reads false. |
VITE_POSTHOG_API_HOST |
No | posthog-js ingestion host. Default https://internal-c.posthog.com. |
VITE_POSTHOG_UI_HOST |
No | posthog-js UI host. Default https://us.i.posthog.com. |
VITE_POSTHOG_ACCESS_TOKEN_OVERRIDE |
No | Dev/test only: a static access token that bypasses the OAuth flow (AUTH_TOKEN_OVERRIDE). Leave unset in production. |
Session recording turns on whenever posthog-js initializes (any build with a
real key); automatic unhandled-error/rejection/console capture is additionally
gated to non-dev (production) builds (capture_exceptions in
posthogAnalyticsImpl.ts).
OAuth redirect URI registration — required for sign-in
The web host reuses the Code ("Array") OAuth application client ids
(packages/agent/packages/agent-contracts/src/oauth.ts). Each region stores its app's redirect_uris
as database rows (Django admin → OAuth applications), and they must include:
https://<web-origin>/callbackfor the deployed host.httpis rejected for non-loopback hosts byOAuthApplicationredirect validation, so the origin must be HTTPS.http://localhost/callback(portless) for local dev — PostHog's authorize view extends RFC 8252 §7.3 loopback port flexibility tolocalhost(posthog/api/oauth/views.py: validate_redirect_uri), so the portless form matches the Vite dev server on any port. If desktop dev builds can already sign in to the region, check whether the registered localhost URI is portless or pinned to:8237.
A CIMD client (like the first-party documents under
https://posthog.com/.well-known/oauth/<app>/client-metadata.json) is NOT suitable: CIMD registrations are capped to
unprivileged scopes, and Code requires scope=* like the desktop app.
S3 artifact-bucket CORS — required for attachment uploads
Composer attachments upload straight from the browser via an S3 presigned POST
(.../artifacts/prepare_upload/ returns the presigned post, then a POST to
s3.<region>.amazonaws.com/<bucket>). The bucket
(posthog-cloud-prod-us-east-1-app-assets for US) must return
Access-Control-Allow-Origin for the web origin or the browser blocks the
response — the POST itself returns 204 (it succeeds server-side) but fetch
rejects with a bare NetworkError. Desktop (Electron/Node fetch) is not
subject to CORS, so this is web-only.
Add the deployed web origin (and http://localhost:5273 for dev) with the
POST method to the bucket's CORS config. Until then, attaching + preview work
but sending a task with an attachment fails at the upload step.
posthog_web integration connect origin — required for Slack / GitHub connect
PostHog brokers the Slack/GitHub OAuth server-side and, on completion, redirects
to a target chosen by the connect_from value (posthog_code →
posthog-code://…, posthog_mobile → posthog://…) — a per-known-client
mapping, not an open redirect. The web host's startFlow opens
.../integrations/authorize/?kind={slack|github}&next=…&connect_from=posthog_web
in a tab; the backend needs a posthog_web mapping for the flow to complete. No
callback relay is required because the integration is created server-side and the
connect hooks refetch getIntegrations() on window-focus. See Known gaps for
what remains once the mapping exists.
CORS — no action needed
Verified against us.posthog.com: /oauth/token answers preflight with the
request origin allowed, and /api/* responds access-control-allow-origin: *
with authorization in the allowed headers. The agent-proxy stream service has
a CORS origin allowlist (TASKS_AGENT_PROXY_CORS_ORIGINS in
PostHog/posthog/services/agent-proxy), and CloudTaskService falls back to
the CORS-open Django stream leg regardless.
Known gaps
Limitations that remain even after the hosting setup above — each needs a code or backend change, not just configuration.
- Slack / GitHub connect is client-wired (
startFlowopens the authorize URL; the connection is detected via a window-focus refetch ofgetIntegrations(), not a callback relay) but gated on backend support for theposthog_webconnect origin (see Hosting). Even with that mapping, the GitHub user flow (POST /api/users/@me/integrations/github/start/) hardcodesconnect_from: "posthog_code"in@posthog/api-clientand returns 400 on web — it needs a host-parameterizedconnect_from. Where a project already has the integration connected, the settings pages render the connected/manage state correctly. - Per-device stores (cloud workspaces, archive, pins, browser tabs) are localStorage-only — not durable across devices or a site-data clear. Desktop persists these in SQLite; the browser host needs server-side state to match.
- Skill dependency expansion is a passthrough: a skill that declares
dependencies:on other skills won't pull them in automatically (pick them explicitly). This is a pipeline gap, not just a web gap —exportSkillstrips SKILL.md frontmatter and the team-skills API has nodependenciesfield, so the dependency list never reaches any client (desktop only expands local on-disk skills). Needsdependenciescarried end-to-end through export → publish → the LlmSkill API (backend) →fetchSkillForInstall.