From 024209c44948f91d4d46f0d37d3f242f409c562b Mon Sep 17 00:00:00 2001
From: Marius Andra <marius@posthog.com>
Date: Wed, 15 Jul 2026 14:28:53 +0200
Subject: [PATCH 1/3] feat(embedded-app): render the real PostHog webapp in-app
 via local auth proxy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EXPERIMENT: <PostHogApp url="/notebooks" /> renders the cloud webapp inside
an iframe, isolated from the React 19 host tree.

- EmbeddedAppProxyService (workspace-server, bound in main like AuthProxy):
  serves an HTML shell booting the webapp's `embed` vite entry, and proxies
  /api, /_preflight, /uploaded_media, /static to PostHog cloud with a fresh
  OAuth Bearer token from AuthService — the iframe sees a same-origin API,
  no CORS, no credentials in the renderer.
- host-router embeddedApp.getUrl starts the proxy lazily and returns its URL.
- packages/ui PostHogApp component + /embedded-app route: iframe plus
  postMessage bridge (navigate, setTheme, ready, routeChanged) synced to the
  host theme store.
- bootstrap: POSTHOG_CODE_APP_NAME env (dev only) isolates userData and the
  single-instance lock so a second dev instance can run beside another
  checkout's app.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/code/src/main/bootstrap.ts               |   6 +-
 apps/code/src/main/di/bindings.ts             |   6 +
 apps/code/src/main/di/container.ts            |  15 +
 apps/code/src/main/trpc/router.ts             |   2 +
 packages/host-router/src/router.ts            |   2 +
 .../src/routers/embedded-app.router.ts        |  15 +
 .../features/embedded-app/EmbeddedAppView.tsx | 139 ++++++++
 packages/ui/src/router/routeTree.gen.ts       |  21 ++
 .../ui/src/router/routes/embedded-app.tsx     |  11 +
 .../embedded-app-proxy.module.ts              |   9 +
 .../embedded-app-proxy/embedded-app-proxy.ts  | 326 ++++++++++++++++++
 .../embedded-app-proxy/identifiers.ts         |  13 +
 12 files changed, 564 insertions(+), 1 deletion(-)
 create mode 100644 packages/host-router/src/routers/embedded-app.router.ts
 create mode 100644 packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
 create mode 100644 packages/ui/src/router/routes/embedded-app.tsx
 create mode 100644 packages/workspace-server/src/services/embedded-app-proxy/embedded-app-proxy.module.ts
 create mode 100644 packages/workspace-server/src/services/embedded-app-proxy/embedded-app-proxy.ts
 create mode 100644 packages/workspace-server/src/services/embedded-app-proxy/identifiers.ts

diff --git a/apps/code/src/main/bootstrap.ts b/apps/code/src/main/bootstrap.ts
index 87f850cb82..f9c7ec5cca 100644
--- a/apps/code/src/main/bootstrap.ts
+++ b/apps/code/src/main/bootstrap.ts
@@ -37,7 +37,11 @@ if (shouldRefuseInternalChildBoot(app.isPackaged, process.env)) {
 const isDev = !app.isPackaged;
 
 // Set app name for single-instance lock, crashReporter, etc
-const appName = isDev ? "posthog-code-dev" : "posthog-code";
+// POSTHOG_CODE_APP_NAME (dev only) isolates userData + the single-instance
+// lock so a second dev instance can run beside another checkout's app.
+const appName = isDev
+  ? (process.env.POSTHOG_CODE_APP_NAME ?? "posthog-code-dev")
+  : "posthog-code";
 app.setName(isDev ? "PostHog Code (Development)" : "PostHog Code");
 
 // Set userData path for @posthog/code
diff --git a/apps/code/src/main/di/bindings.ts b/apps/code/src/main/di/bindings.ts
index 1c3db763fa..5632515d8b 100644
--- a/apps/code/src/main/di/bindings.ts
+++ b/apps/code/src/main/di/bindings.ts
@@ -149,6 +149,10 @@ import type {
 } from "@posthog/workspace-server/services/archive/ports";
 import type { AUTH_PROXY_AUTH } from "@posthog/workspace-server/services/auth-proxy/identifiers";
 import type { AuthProxyAuth } from "@posthog/workspace-server/services/auth-proxy/ports";
+import type {
+  EMBEDDED_APP_PROXY_AUTH,
+  EmbeddedAppProxyAuth,
+} from "@posthog/workspace-server/services/embedded-app-proxy/identifiers";
 import type {
   ENRICHMENT_AUTH,
   ENRICHMENT_FILE_READER,
@@ -361,6 +365,8 @@ export interface MainBindings {
   // Auth proxy / mcp proxy
   [AUTH_PROXY_AUTH]: AuthProxyAuth;
   [MCP_PROXY_AUTH]: McpProxyAuth;
+  // EXPERIMENT (embedded webapp)
+  [EMBEDDED_APP_PROXY_AUTH]: EmbeddedAppProxyAuth;
 
   // Archive / suspension host ports
   [ARCHIVE_SESSION_CANCELLER]: SessionCanceller;
diff --git a/apps/code/src/main/di/container.ts b/apps/code/src/main/di/container.ts
index e620dce39d..e4c6c337ed 100644
--- a/apps/code/src/main/di/container.ts
+++ b/apps/code/src/main/di/container.ts
@@ -119,6 +119,7 @@ import { STORAGE_PATHS_SERVICE } from "@posthog/platform/storage-paths";
 import { UPDATER_SERVICE } from "@posthog/platform/updater";
 import { URL_LAUNCHER_SERVICE } from "@posthog/platform/url-launcher";
 import { WORKSPACE_SETTINGS_SERVICE } from "@posthog/platform/workspace-settings";
+import { getCloudUrlFromRegion } from "@posthog/shared";
 import type { WorkspaceClient } from "@posthog/workspace-client/client";
 import { databaseModule } from "@posthog/workspace-server/db/db.module";
 import {
@@ -155,6 +156,8 @@ import { authProxyModule } from "@posthog/workspace-server/services/auth-proxy/a
 import { AUTH_PROXY_AUTH } from "@posthog/workspace-server/services/auth-proxy/identifiers";
 import { browserTabsModule } from "@posthog/workspace-server/services/browser-tabs/browser-tabs.module";
 import { claudeCliSessionsModule } from "@posthog/workspace-server/services/claude-cli-sessions/claude-cli-sessions.module";
+import { embeddedAppProxyModule } from "@posthog/workspace-server/services/embedded-app-proxy/embedded-app-proxy.module";
+import { EMBEDDED_APP_PROXY_AUTH } from "@posthog/workspace-server/services/embedded-app-proxy/identifiers";
 import { enrichmentModule } from "@posthog/workspace-server/services/enrichment/enrichment.module";
 import {
   ENRICHMENT_AUTH,
@@ -380,6 +383,18 @@ container.bind(AUTH_PROXY_AUTH).toDynamicValue((ctx) => ({
       .get<AuthService>(MAIN_AUTH_SERVICE)
       .authenticatedFetch(fetch, url, init),
 }));
+// EXPERIMENT (embedded webapp): local same-origin proxy for the iframe'd app
+container.load(embeddedAppProxyModule);
+container.bind(EMBEDDED_APP_PROXY_AUTH).toDynamicValue((ctx) => ({
+  authenticatedFetch: (url: string, init?: RequestInit) =>
+    ctx
+      .get<AuthService>(MAIN_AUTH_SERVICE)
+      .authenticatedFetch(fetch, url, init),
+  getUpstreamUrl: async () => {
+    const state = ctx.get<AuthService>(MAIN_AUTH_SERVICE).getState();
+    return getCloudUrlFromRegion(state.cloudRegion ?? "us");
+  },
+}));
 container.load(mcpProxyModule);
 container.bind(MCP_PROXY_AUTH).toDynamicValue((ctx) => {
   const auth = () => ctx.get<AuthService>(MAIN_AUTH_SERVICE);
diff --git a/apps/code/src/main/trpc/router.ts b/apps/code/src/main/trpc/router.ts
index c6bd789ffe..6d963c38c8 100644
--- a/apps/code/src/main/trpc/router.ts
+++ b/apps/code/src/main/trpc/router.ts
@@ -15,6 +15,7 @@ import { connectivityRouter } from "@posthog/host-router/routers/connectivity.ro
 import { contextMenuRouter } from "@posthog/host-router/routers/context-menu.router";
 import { dashboardsRouter } from "@posthog/host-router/routers/dashboards.router";
 import { deepLinkRouter } from "@posthog/host-router/routers/deep-link.router";
+import { embeddedAppRouter } from "@posthog/host-router/routers/embedded-app.router";
 import { enrichmentRouter } from "@posthog/host-router/routers/enrichment.router";
 import { environmentRouter } from "@posthog/host-router/routers/environment.router";
 import { externalAppsRouter } from "@posthog/host-router/routers/external-apps.router";
@@ -72,6 +73,7 @@ export const trpcRouter = router({
   contextMenu: contextMenuRouter,
   dev: devRouter,
   discordPresence: discordPresenceRouter,
+  embeddedApp: embeddedAppRouter,
   enrichment: enrichmentRouter,
   environment: environmentRouter,
   encryption: encryptionRouter,
diff --git a/packages/host-router/src/router.ts b/packages/host-router/src/router.ts
index 71f787c4c2..577dcf7dda 100644
--- a/packages/host-router/src/router.ts
+++ b/packages/host-router/src/router.ts
@@ -14,6 +14,7 @@ import { connectivityRouter } from "./routers/connectivity.router";
 import { contextMenuRouter } from "./routers/context-menu.router";
 import { dashboardsRouter } from "./routers/dashboards.router";
 import { deepLinkRouter } from "./routers/deep-link.router";
+import { embeddedAppRouter } from "./routers/embedded-app.router";
 import { enrichmentRouter } from "./routers/enrichment.router";
 import { environmentRouter } from "./routers/environment.router";
 import { externalAppsRouter } from "./routers/external-apps.router";
@@ -64,6 +65,7 @@ export const hostRouter = router({
   contextMenu: contextMenuRouter,
   dashboards: dashboardsRouter,
   deepLink: deepLinkRouter,
+  embeddedApp: embeddedAppRouter,
   enrichment: enrichmentRouter,
   environment: environmentRouter,
   externalApps: externalAppsRouter,
diff --git a/packages/host-router/src/routers/embedded-app.router.ts b/packages/host-router/src/routers/embedded-app.router.ts
new file mode 100644
index 0000000000..529068324e
--- /dev/null
+++ b/packages/host-router/src/routers/embedded-app.router.ts
@@ -0,0 +1,15 @@
+import { publicProcedure, router } from "@posthog/host-trpc/trpc";
+import type { EmbeddedAppProxyService } from "@posthog/workspace-server/services/embedded-app-proxy/embedded-app-proxy";
+import { EMBEDDED_APP_PROXY_SERVICE } from "@posthog/workspace-server/services/embedded-app-proxy/identifiers";
+import { z } from "zod";
+
+/** EXPERIMENT (embedded webapp): expose the local proxy URL to the renderer. */
+export const embeddedAppRouter = router({
+  getUrl: publicProcedure
+    .output(z.object({ url: z.string() }))
+    .query(async ({ ctx }) => ({
+      url: await ctx.container
+        .get<EmbeddedAppProxyService>(EMBEDDED_APP_PROXY_SERVICE)
+        .ensureStarted(),
+    })),
+});
diff --git a/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx b/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
new file mode 100644
index 0000000000..b48e1fef6f
--- /dev/null
+++ b/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
@@ -0,0 +1,139 @@
+import { useHostTRPC } from "@posthog/host-router/react";
+import { Button } from "@posthog/quill";
+import { useQuery } from "@tanstack/react-query";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useThemeStore } from "../../shell/themeStore";
+
+/**
+ * EXPERIMENT (embedded webapp): renders the real PostHog webapp in an iframe.
+ *
+ * The iframe points at a local main-process proxy that serves the webapp
+ * shell and forwards /api to PostHog cloud with the app's OAuth token, so
+ * the webapp sees a same-origin cookie-less API. A postMessage bridge keeps
+ * navigation and theme in sync (see frontend/src/embed/bridge.ts in the
+ * posthog repo).
+ */
+
+const FROM_EMBED = "posthog-embed";
+const FROM_HOST = "posthog-embed-host";
+
+const QUICK_LINKS: Array<{ label: string; path: string }> = [
+  { label: "Notebooks", path: "/notebooks" },
+  { label: "Feature flags", path: "/feature_flags" },
+  { label: "Dashboards", path: "/dashboard" },
+  { label: "Activity", path: "/activity/explore" },
+];
+
+interface PostHogAppProps {
+  /** Initial webapp path, e.g. "/notebooks" */
+  url: string;
+}
+
+export function PostHogApp({ url: initialPath }: PostHogAppProps) {
+  const trpc = useHostTRPC();
+  const { data, error, isLoading } = useQuery(
+    trpc.embeddedApp.getUrl.queryOptions(undefined, {
+      staleTime: Number.POSITIVE_INFINITY,
+      retry: 1,
+    }),
+  );
+  const isDarkMode = useThemeStore((s) => s.isDarkMode);
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const [embedRoute, setEmbedRoute] = useState<string | null>(null);
+  const [ready, setReady] = useState(false);
+
+  // Compute the iframe src once per proxy URL: theme changes and navigation
+  // afterwards go over the bridge instead of reloading the iframe.
+  const initialThemeRef = useRef(isDarkMode ? "dark" : "light");
+  const iframeSrc = useMemo(() => {
+    if (!data?.url) return null;
+    return `${data.url}${initialPath}?__posthog_embed_theme=${initialThemeRef.current}`;
+  }, [data?.url, initialPath]);
+
+  const postToEmbed = useCallback((message: Record<string, unknown>) => {
+    iframeRef.current?.contentWindow?.postMessage(
+      { source: FROM_HOST, ...message },
+      "*",
+    );
+  }, []);
+
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      const data: unknown = event.data;
+      if (
+        !data ||
+        typeof data !== "object" ||
+        (data as Record<string, unknown>).source !== FROM_EMBED ||
+        event.source !== iframeRef.current?.contentWindow
+      ) {
+        return;
+      }
+      const message = data as { type?: string; url?: unknown };
+      if (message.type === "ready") {
+        setReady(true);
+        if (typeof message.url === "string") setEmbedRoute(message.url);
+      } else if (
+        message.type === "routeChanged" &&
+        typeof message.url === "string"
+      ) {
+        setEmbedRoute(message.url);
+      }
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, []);
+
+  // Host theme wins: push it whenever it changes (and once the embed is ready).
+  useEffect(() => {
+    if (ready) {
+      postToEmbed({ type: "setTheme", theme: isDarkMode ? "dark" : "light" });
+    }
+  }, [ready, isDarkMode, postToEmbed]);
+
+  const navigate = useCallback(
+    (path: string) => postToEmbed({ type: "navigate", url: path }),
+    [postToEmbed],
+  );
+
+  if (isLoading) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm opacity-70">
+        Starting embedded PostHog…
+      </div>
+    );
+  }
+  if (error || !iframeSrc) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm opacity-70">
+        Could not start the embedded PostHog proxy
+        {error ? `: ${String(error)}` : ""}
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="flex items-center gap-2 border-b px-2 py-1">
+        {QUICK_LINKS.map((link) => (
+          <Button
+            key={link.path}
+            variant="outline"
+            size="sm"
+            onClick={() => navigate(link.path)}
+          >
+            {link.label}
+          </Button>
+        ))}
+        <span className="ml-auto truncate font-mono text-xs opacity-60">
+          {ready ? (embedRoute ?? "") : "connecting…"}
+        </span>
+      </div>
+      <iframe
+        ref={iframeRef}
+        src={iframeSrc}
+        title="PostHog"
+        className="min-h-0 w-full flex-1 border-0"
+      />
+    </div>
+  );
+}
diff --git a/packages/ui/src/router/routeTree.gen.ts b/packages/ui/src/router/routeTree.gen.ts
index a148662ad7..4bd7e61e10 100644
--- a/packages/ui/src/router/routeTree.gen.ts
+++ b/packages/ui/src/router/routeTree.gen.ts
@@ -13,6 +13,7 @@ import { Route as WebsiteRouteImport } from './routes/website'
 import { Route as UsageRouteImport } from './routes/usage'
 import { Route as SkillsRouteImport } from './routes/skills'
 import { Route as McpServersRouteImport } from './routes/mcp-servers'
+import { Route as EmbeddedAppRouteImport } from './routes/embedded-app'
 import { Route as CommandCenterRouteImport } from './routes/command-center'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as WebsiteIndexRouteImport } from './routes/website/index'
@@ -98,6 +99,11 @@ const McpServersRoute = McpServersRouteImport.update({
   path: '/mcp-servers',
   getParentRoute: () => rootRouteImport,
 } as any)
+const EmbeddedAppRoute = EmbeddedAppRouteImport.update({
+  id: '/embedded-app',
+  path: '/embedded-app',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const CommandCenterRoute = CommandCenterRouteImport.update({
   id: '/command-center',
   path: '/command-center',
@@ -444,6 +450,7 @@ const CodeAgentsApplicationsIdOrSlugSessionsSessionIdRoute =
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/command-center': typeof CommandCenterRoute
+  '/embedded-app': typeof EmbeddedAppRoute
   '/mcp-servers': typeof McpServersRoute
   '/skills': typeof SkillsRoute
   '/usage': typeof UsageRoute
@@ -514,6 +521,7 @@ export interface FileRoutesByFullPath {
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/command-center': typeof CommandCenterRoute
+  '/embedded-app': typeof EmbeddedAppRoute
   '/mcp-servers': typeof McpServersRoute
   '/skills': typeof SkillsRoute
   '/usage': typeof UsageRoute
@@ -574,6 +582,7 @@ export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
   '/command-center': typeof CommandCenterRoute
+  '/embedded-app': typeof EmbeddedAppRoute
   '/mcp-servers': typeof McpServersRoute
   '/skills': typeof SkillsRoute
   '/usage': typeof UsageRoute
@@ -646,6 +655,7 @@ export interface FileRouteTypes {
   fullPaths:
     | '/'
     | '/command-center'
+    | '/embedded-app'
     | '/mcp-servers'
     | '/skills'
     | '/usage'
@@ -716,6 +726,7 @@ export interface FileRouteTypes {
   to:
     | '/'
     | '/command-center'
+    | '/embedded-app'
     | '/mcp-servers'
     | '/skills'
     | '/usage'
@@ -775,6 +786,7 @@ export interface FileRouteTypes {
     | '__root__'
     | '/'
     | '/command-center'
+    | '/embedded-app'
     | '/mcp-servers'
     | '/skills'
     | '/usage'
@@ -846,6 +858,7 @@ export interface FileRouteTypes {
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
   CommandCenterRoute: typeof CommandCenterRoute
+  EmbeddedAppRoute: typeof EmbeddedAppRoute
   McpServersRoute: typeof McpServersRoute
   SkillsRoute: typeof SkillsRoute
   UsageRoute: typeof UsageRoute
@@ -895,6 +908,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof McpServersRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/embedded-app': {
+      id: '/embedded-app'
+      path: '/embedded-app'
+      fullPath: '/embedded-app'
+      preLoaderRoute: typeof EmbeddedAppRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/command-center': {
       id: '/command-center'
       path: '/command-center'
@@ -1570,6 +1590,7 @@ const CodeInboxRouteWithChildren = CodeInboxRoute._addFileChildren(
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
   CommandCenterRoute: CommandCenterRoute,
+  EmbeddedAppRoute: EmbeddedAppRoute,
   McpServersRoute: McpServersRoute,
   SkillsRoute: SkillsRoute,
   UsageRoute: UsageRoute,
diff --git a/packages/ui/src/router/routes/embedded-app.tsx b/packages/ui/src/router/routes/embedded-app.tsx
new file mode 100644
index 0000000000..269ef22f48
--- /dev/null
+++ b/packages/ui/src/router/routes/embedded-app.tsx
@@ -0,0 +1,11 @@
+import { PostHogApp } from "@posthog/ui/features/embedded-app/EmbeddedAppView";
+import { createFileRoute } from "@tanstack/react-router";
+
+/** EXPERIMENT (embedded webapp): dev route hosting the iframe'd PostHog app. */
+export const Route = createFileRoute("/embedded-app")({
+  component: EmbeddedAppRoute,
+});
+
+function EmbeddedAppRoute() {
+  return <PostHogApp url="/notebooks" />;
+}
diff --git a/packages/workspace-server/src/services/embedded-app-proxy/embedded-app-proxy.module.ts b/packages/workspace-server/src/services/embedded-app-proxy/embedded-app-proxy.module.ts
new file mode 100644
index 0000000000..a35b488100
--- /dev/null
+++ b/packages/workspace-server/src/services/embedded-app-proxy/embedded-app-proxy.module.ts
@@ -0,0 +1,9 @@
+import { ContainerModule } from "inversify";
+import { EmbeddedAppProxyService } from "./embedded-app-proxy";
+import { EMBEDDED_APP_PROXY_SERVICE } from "./identifiers";
+
+export const embeddedAppProxyModule = new ContainerModule(({ bind }) => {
+  bind(EMBEDDED_APP_PROXY_SERVICE)
+    .to(EmbeddedAppProxyService)
+    .inSingletonScope();
+});
diff --git a/packages/workspace-server/src/services/embedded-app-proxy/embedded-app-proxy.ts b/packages/workspace-server/src/services/embedded-app-proxy/embedded-app-proxy.ts
new file mode 100644
index 0000000000..6afcc5411a
--- /dev/null
+++ b/packages/workspace-server/src/services/embedded-app-proxy/embedded-app-proxy.ts
@@ -0,0 +1,326 @@
+import http from "node:http";
+import {
+  ROOT_LOGGER,
+  type RootLogger,
+  type ScopedLogger,
+} from "@posthog/di/logger";
+import { serializeError } from "@posthog/shared";
+import { inject, injectable } from "inversify";
+import {
+  type StreamProgress,
+  streamBodyToResponse,
+} from "../proxy-stream/proxy-stream";
+import type { EmbeddedAppProxyAuth } from "./identifiers";
+import { EMBEDDED_APP_PROXY_AUTH } from "./identifiers";
+
+export interface EmbeddedAppProxyOptions {
+  /** PostHog cloud origin, e.g. https://us.posthog.com */
+  upstreamUrl: string;
+  /**
+   * Where the webapp's JS/CSS come from. During the experiment this is the
+   * posthog repo's vite dev server (e.g. http://localhost:8135); production
+   * packaging would serve a built `dist/` from here instead.
+   */
+  assetsUrl: string;
+  /** Fixed port for dev harnesses; defaults to an OS-assigned port. */
+  port?: number;
+}
+
+/**
+ * EXPERIMENT (embedded webapp): local same-origin server for the PostHog
+ * webapp running inside an iframe of the desktop app.
+ *
+ * Modeled on AuthProxyService. Two jobs:
+ *  1. Serve a minimal HTML shell (history-API fallback for every non-API GET)
+ *     that boots the webapp's `embed` vite entry.
+ *  2. Proxy backend paths (/api, /_preflight, ...) to PostHog cloud, stripping
+ *     browser credentials and injecting a fresh OAuth Bearer token via the
+ *     host-supplied authenticatedFetch. The iframe therefore sees a plain
+ *     same-origin session-style API and no CORS is involved.
+ */
+@injectable()
+export class EmbeddedAppProxyService {
+  private server: http.Server | null = null;
+  private options: EmbeddedAppProxyOptions | null = null;
+  private port: number | null = null;
+  private readonly log: ScopedLogger;
+
+  constructor(
+    @inject(EMBEDDED_APP_PROXY_AUTH)
+    private readonly auth: EmbeddedAppProxyAuth,
+    @inject(ROOT_LOGGER)
+    rootLogger: RootLogger,
+  ) {
+    this.log = rootLogger.scope("embedded-app-proxy");
+  }
+
+  /** Path prefixes forwarded to PostHog cloud; everything else is the shell. */
+  private static readonly UPSTREAM_PREFIXES = [
+    "/api/",
+    "/_preflight",
+    "/uploaded_media/",
+    "/media/",
+    "/static/",
+  ];
+
+  /**
+   * Idempotent start with host-derived defaults; used by the host router.
+   * Assets come from the posthog repo's vite dev server during the experiment
+   * (override with POSTHOG_EMBED_ASSETS_URL).
+   */
+  async ensureStarted(): Promise<string> {
+    if (this.isRunning()) {
+      return this.getProxyUrl();
+    }
+    const upstreamUrl = await this.auth.getUpstreamUrl();
+    const assetsUrl =
+      process.env.POSTHOG_EMBED_ASSETS_URL ?? "http://localhost:8135";
+    return this.start({ upstreamUrl, assetsUrl });
+  }
+
+  async start(options: EmbeddedAppProxyOptions): Promise<string> {
+    if (this.server) {
+      this.options = options;
+      return this.getProxyUrl();
+    }
+    this.options = options;
+
+    this.server = http.createServer((req, res) => {
+      this.handleRequest(req, res);
+    });
+
+    return new Promise<string>((resolve, reject) => {
+      this.server?.listen(options.port ?? 0, "127.0.0.1", () => {
+        const addr = this.server?.address();
+        if (typeof addr === "object" && addr) {
+          this.port = addr.port;
+          this.log.info("Embedded app proxy started", {
+            url: this.getProxyUrl(),
+            upstream: options.upstreamUrl,
+            assets: options.assetsUrl,
+          });
+          resolve(this.getProxyUrl());
+        } else {
+          reject(new Error("Failed to get embedded app proxy address"));
+        }
+      });
+      this.server?.on("error", (err) => {
+        this.log.error("Embedded app proxy server error", err);
+        reject(err);
+      });
+    });
+  }
+
+  getProxyUrl(): string {
+    if (!this.port) {
+      throw new Error("Embedded app proxy not started");
+    }
+    return `http://127.0.0.1:${this.port}`;
+  }
+
+  isRunning(): boolean {
+    return this.server !== null && this.port !== null;
+  }
+
+  async stop(): Promise<void> {
+    if (!this.server) return;
+    return new Promise<void>((resolve) => {
+      this.server?.close(() => {
+        this.log.info("Embedded app proxy stopped");
+        this.server = null;
+        this.port = null;
+        resolve();
+      });
+    });
+  }
+
+  private handleRequest(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+  ): void {
+    const options = this.options;
+    if (!options) {
+      res.writeHead(503);
+      res.end("Proxy not configured");
+      return;
+    }
+
+    const pathname = (req.url ?? "/").split("?")[0] ?? "/";
+    const isUpstream = EmbeddedAppProxyService.UPSTREAM_PREFIXES.some(
+      (prefix) =>
+        pathname.startsWith(prefix) ||
+        pathname === prefix.replace(/\/$/, "") ||
+        `${pathname}/` === prefix,
+    );
+
+    if (!isUpstream) {
+      if (req.method === "GET" || req.method === "HEAD") {
+        const html = this.buildShellHtml(options);
+        res.writeHead(200, {
+          "content-type": "text/html; charset=utf-8",
+          "cache-control": "no-store",
+        });
+        res.end(req.method === "HEAD" ? undefined : html);
+      } else {
+        res.writeHead(404);
+        res.end("Not found");
+      }
+      return;
+    }
+
+    const base = options.upstreamUrl.endsWith("/")
+      ? options.upstreamUrl
+      : `${options.upstreamUrl}/`;
+    const incoming = (req.url ?? "/").replace(/^\//, "");
+    const targetUrl = new URL(incoming, base);
+
+    const upstreamBase = new URL(base);
+    const sameOrigin =
+      targetUrl.protocol === upstreamBase.protocol &&
+      targetUrl.host === upstreamBase.host;
+    if (!sameOrigin || targetUrl.pathname.includes("..")) {
+      this.log.warn("Rejected embedded app proxy request", {
+        method: req.method,
+        incoming: req.url,
+      });
+      res.writeHead(403);
+      res.end("Forbidden");
+      return;
+    }
+
+    // Strip anything credential-shaped or origin-revealing: the upstream
+    // request is authenticated solely by the injected Bearer token, and
+    // cookies/origin/referer from the local shell would confuse Django's
+    // session/CSRF machinery.
+    const strippedHeaders = new Set([
+      "host",
+      "connection",
+      "cookie",
+      "origin",
+      "referer",
+      "authorization",
+      "x-api-key",
+      "api-key",
+      "proxy-authorization",
+      "accept-encoding",
+      "x-csrftoken",
+    ]);
+    const headers: Record<string, string> = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+      if (strippedHeaders.has(key)) continue;
+      if (typeof value === "string") headers[key] = value;
+    }
+
+    const abort = new AbortController();
+    res.on("close", () => {
+      if (!res.writableEnded) {
+        abort.abort();
+      }
+    });
+
+    const fetchOptions: RequestInit = {
+      method: req.method ?? "GET",
+      headers,
+      signal: abort.signal,
+    };
+
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk: Buffer) => chunks.push(chunk));
+      req.on("end", () => {
+        fetchOptions.body = Buffer.concat(chunks);
+        void this.forwardRequest(targetUrl.toString(), fetchOptions, res);
+      });
+    } else {
+      void this.forwardRequest(targetUrl.toString(), fetchOptions, res);
+    }
+  }
+
+  private buildShellHtml(options: EmbeddedAppProxyOptions): string {
+    const assets = options.assetsUrl.replace(/\/$/, "");
+    // Dev-server variant: load the embed entry straight from vite, with the
+    // react-refresh preamble vite's Django template would normally inject.
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>PostHog (embedded)</title>
+<script>
+  window.JS_URL = ${JSON.stringify(assets)};
+  window.__POSTHOG_EMBED__ = true;
+</script>
+<script type="module">
+  import RefreshRuntime from ${JSON.stringify(`${assets}/@react-refresh`)};
+  RefreshRuntime.injectIntoGlobalHook(window);
+  window.$RefreshReg$ = () => {};
+  window.$RefreshSig$ = () => (type) => type;
+  window.__vite_plugin_react_preamble_installed__ = true;
+</script>
+<script type="module" src="${assets}/@vite/client"></script>
+<script type="module" src="${assets}/src/embed/index.tsx"></script>
+</head>
+<body>
+<div id="root"></div>
+</body>
+</html>`;
+  }
+
+  private async forwardRequest(
+    url: string,
+    options: RequestInit,
+    res: http.ServerResponse,
+  ): Promise<void> {
+    const startedAt = Date.now();
+    const progress: StreamProgress = { bytesWritten: 0 };
+    let status = 0;
+    try {
+      const response = await this.auth.authenticatedFetch(url, options);
+      status = response.status;
+
+      const stripHeaders = new Set([
+        "transfer-encoding",
+        "content-encoding",
+        "content-length",
+        "set-cookie",
+        "content-security-policy",
+        "x-frame-options",
+      ]);
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value: string, key: string) => {
+        if (stripHeaders.has(key)) return;
+        responseHeaders[key] = value;
+      });
+
+      res.writeHead(response.status, responseHeaders);
+      await streamBodyToResponse(response.body, res, progress);
+
+      if (status >= 400) {
+        this.log.warn("Embedded app proxy upstream error", {
+          url,
+          method: options.method,
+          status,
+          durationMs: Date.now() - startedAt,
+        });
+      }
+    } catch (err) {
+      if (options.signal?.aborted) {
+        this.log.debug("Upstream fetch aborted after client disconnect", {
+          url,
+        });
+      } else {
+        this.log.error("Embedded app proxy forward error", {
+          url,
+          method: options.method,
+          status,
+          durationMs: Date.now() - startedAt,
+          errorDetail: serializeError(err),
+        });
+      }
+      if (!res.headersSent) {
+        res.writeHead(502);
+      }
+      res.end("Proxy error");
+    }
+  }
+}
diff --git a/packages/workspace-server/src/services/embedded-app-proxy/identifiers.ts b/packages/workspace-server/src/services/embedded-app-proxy/identifiers.ts
new file mode 100644
index 0000000000..dec74d8221
--- /dev/null
+++ b/packages/workspace-server/src/services/embedded-app-proxy/identifiers.ts
@@ -0,0 +1,13 @@
+export const EMBEDDED_APP_PROXY_SERVICE = Symbol.for(
+  "posthog.workspace.embeddedAppProxyService",
+);
+export const EMBEDDED_APP_PROXY_AUTH = Symbol.for(
+  "posthog.workspace.embeddedAppProxyAuth",
+);
+
+/** Token-injecting fetch supplied by the host (main process AuthService). */
+export interface EmbeddedAppProxyAuth {
+  authenticatedFetch(url: string, init?: RequestInit): Promise<Response>;
+  /** Cloud origin for the signed-in region, e.g. https://us.posthog.com */
+  getUpstreamUrl(): Promise<string>;
+}

From e44923a7cb81e2c91e14cf564a9fd8428afcc62c Mon Sep 17 00:00:00 2001
From: Marius Andra <marius@posthog.com>
Date: Wed, 15 Jul 2026 14:31:05 +0200
Subject: [PATCH 2/3] fix(embedded-app): re-sync host theme on every iframe
 ready

An iframe reload sends ready again but the ready state is already true, so
the theme effect wouldn't re-run and the embed could boot with a stale theme.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../ui/src/features/embedded-app/EmbeddedAppView.tsx | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx b/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
index b48e1fef6f..991809c8d9 100644
--- a/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
+++ b/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
@@ -57,6 +57,10 @@ export function PostHogApp({ url: initialPath }: PostHogAppProps) {
     );
   }, []);
 
+  // Read inside the message handler without re-subscribing on theme changes.
+  const isDarkModeRef = useRef(isDarkMode);
+  isDarkModeRef.current = isDarkMode;
+
   useEffect(() => {
     const onMessage = (event: MessageEvent) => {
       const data: unknown = event.data;
@@ -72,6 +76,12 @@ export function PostHogApp({ url: initialPath }: PostHogAppProps) {
       if (message.type === "ready") {
         setReady(true);
         if (typeof message.url === "string") setEmbedRoute(message.url);
+        // Re-sync theme on every ready — the iframe may have reloaded and
+        // `ready` state (already true) won't re-run the theme effect.
+        postToEmbed({
+          type: "setTheme",
+          theme: isDarkModeRef.current ? "dark" : "light",
+        });
       } else if (
         message.type === "routeChanged" &&
         typeof message.url === "string"
@@ -81,7 +91,7 @@ export function PostHogApp({ url: initialPath }: PostHogAppProps) {
     };
     window.addEventListener("message", onMessage);
     return () => window.removeEventListener("message", onMessage);
-  }, []);
+  }, [postToEmbed]);
 
   // Host theme wins: push it whenever it changes (and once the embed is ready).
   useEffect(() => {

From 53b78786299382104dad93de802ba5110e6287f3 Mon Sep 17 00:00:00 2001
From: Marius Andra <marius@posthog.com>
Date: Wed, 15 Jul 2026 16:56:16 +0200
Subject: [PATCH 3/3] feat(embedded-app): browser-tab integration for embedded
 webapp surfaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The embedded webapp is now a first-class browser tab:

- /embedded-app takes a `path` search param; each distinct webapp path is
  its own tab identity, encoded into the tab's appView string
  ("embedded-app:<path>") — the browser-tabs domain treats appView as an
  opaque string, so dedup/focus works per path with no schema change.
- useAppView maps the route (with its search path), BrowserTabStrip labels
  embedded tabs "PostHog <path>" with a globe icon and navigates them back
  to /embedded-app?path=... on select.
- useOpenEmbeddedAppTab opens (or focuses) a NEW tab: it mirrors the
  strip's open flow — openOrFocus transform applied local-first, persisted
  in the background, then a navigation stamped with the tab id — because a
  plain router navigation is in-tab by design and would retarget the
  current tab.
- PostHogApp handles the bridge's `openTab` messages (window.open /
  target=_blank inside the webapp) by opening a host tab at the normalized
  path (/project/<id> prefix stripped so identities stay stable), and grows
  a "+ New tab" toolbar affordance for the current embedded page.

Verified live: nav chrome hidden (posthog-side embedMode), scene
full-width, window.open in the embed spawns a second "PostHog /notebooks/…"
tab, tabs persist across app restart and switch correctly, theme and
navigation bridges intact.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../features/browser-tabs/BrowserTabStrip.tsx | 30 ++++++++-
 .../browser-tabs/useOpenEmbeddedAppTab.ts     | 62 +++++++++++++++++++
 .../features/embedded-app/EmbeddedAppView.tsx | 35 ++++++++++-
 .../features/embedded-app/embeddedAppTab.ts   | 29 +++++++++
 .../ui/src/router/routes/embedded-app.tsx     | 16 ++++-
 packages/ui/src/router/useAppView.ts          | 30 +++++++--
 6 files changed, 193 insertions(+), 9 deletions(-)
 create mode 100644 packages/ui/src/features/browser-tabs/useOpenEmbeddedAppTab.ts
 create mode 100644 packages/ui/src/features/embedded-app/embeddedAppTab.ts

diff --git a/packages/ui/src/features/browser-tabs/BrowserTabStrip.tsx b/packages/ui/src/features/browser-tabs/BrowserTabStrip.tsx
index bd52aef08e..39600fab8c 100644
--- a/packages/ui/src/features/browser-tabs/BrowserTabStrip.tsx
+++ b/packages/ui/src/features/browser-tabs/BrowserTabStrip.tsx
@@ -1,5 +1,6 @@
 import {
   BrainIcon,
+  GlobeIcon,
   HouseIcon,
   PlugsConnectedIcon,
   RobotIcon,
@@ -35,6 +36,10 @@ import {
 } from "@posthog/ui/features/canvas/hooks/useDashboards";
 import { PERSONAL_CHANNEL_NAME } from "@posthog/ui/features/canvas/hooks/useTaskChannels";
 import { SHORTCUTS } from "@posthog/ui/features/command/keyboard-shortcuts";
+import {
+  embeddedAppTabPath,
+  embeddedAppTabView,
+} from "@posthog/ui/features/embedded-app/embeddedAppTab";
 import { useFeatureFlag } from "@posthog/ui/features/feature-flags/useFeatureFlag";
 import { usePanelLayoutStore } from "@posthog/ui/features/panels/panelLayoutStore";
 import { getLeafPanel } from "@posthog/ui/features/panels/panelStoreHelpers";
@@ -183,7 +188,12 @@ export function BrowserTabStrip() {
   // Home) are tab targets too. useAppView normalizes both the /code routes and
   // their /website mirrors to the same view.type, so a tab survives either space.
   const view = useAppView();
-  const routeAppView: AppView | null = isAppView(view.type) ? view.type : null;
+  const routeAppView: string | null =
+    view.type === "embedded-app"
+      ? embeddedAppTabView(view.embedPath ?? "/notebooks")
+      : isAppView(view.type)
+        ? view.type
+        : null;
 
   const { channels } = useChannels();
   const { createChannel } = useChannelMutations();
@@ -533,6 +543,17 @@ export function BrowserTabStrip() {
             pinned,
           };
         }
+        // An embedded PostHog webapp tab — label by its webapp path.
+        const embedPath = embeddedAppTabPath(appView);
+        if (embedPath !== null) {
+          return {
+            id: t.id,
+            label: `PostHog ${embedPath.split("?")[0] || "/"}`,
+            icon: <GlobeIcon size={14} />,
+            channelName: null,
+            pinned,
+          };
+        }
         // A top-level app page (Inbox, Agents, Skills, …).
         if (appView && isAppView(appView)) {
           return {
@@ -601,6 +622,13 @@ export function BrowserTabStrip() {
       } else {
         navigate({ to: "/website/$channelId", params, state });
       }
+    } else if (tab.appView && embeddedAppTabPath(tab.appView) !== null) {
+      // An embedded PostHog webapp tab — its route carries the path in search.
+      navigate({
+        to: "/embedded-app",
+        search: { path: embeddedAppTabPath(tab.appView) ?? undefined },
+        state,
+      });
     } else if (tab.appView && isAppView(tab.appView)) {
       // A top-level app page — back to its canonical route (literal `to` per
       // case so the router types stay checked).
diff --git a/packages/ui/src/features/browser-tabs/useOpenEmbeddedAppTab.ts b/packages/ui/src/features/browser-tabs/useOpenEmbeddedAppTab.ts
new file mode 100644
index 0000000000..bcf7a2868e
--- /dev/null
+++ b/packages/ui/src/features/browser-tabs/useOpenEmbeddedAppTab.ts
@@ -0,0 +1,62 @@
+import { useHostTRPCClient } from "@posthog/host-router/react";
+import { openOrFocusTab, primaryWindow } from "@posthog/shared";
+import { embeddedAppTabView } from "@posthog/ui/features/embedded-app/embeddedAppTab";
+import { useNavigate } from "@tanstack/react-router";
+import { useCallback } from "react";
+import { applyLocalTransform, persistWrite, readMirror } from "./tabsSync";
+
+/**
+ * EXPERIMENT (embedded webapp): open (or focus) a browser tab hosting the
+ * embedded PostHog webapp at `path`.
+ *
+ * A plain router navigation is in-tab by design (the strip's navigation
+ * effect retargets the active tab), so opening a NEW tab mirrors the strip's
+ * own flow: apply the openOrFocus transform to the mirror local-first,
+ * persist in the background, then navigate with the history entry stamped
+ * with the tab id so the effect activates that tab instead of retargeting.
+ */
+export function useOpenEmbeddedAppTab(): (path: string) => void {
+  const hostClient = useHostTRPCClient();
+  const navigate = useNavigate();
+
+  return useCallback(
+    (path: string) => {
+      const appView = embeddedAppTabView(path);
+      const windowId = primaryWindow(readMirror())?.id;
+      let tabId: string | undefined;
+      if (windowId) {
+        const input = {
+          windowId,
+          dashboardId: null,
+          taskId: null,
+          channelId: null,
+          channelSection: null,
+          appView,
+        };
+        const mintedId = crypto.randomUUID();
+        tabId = mintedId;
+        applyLocalTransform((s) => {
+          const result = openOrFocusTab(s, {
+            ...input,
+            makeId: () => mintedId,
+            now: Date.now,
+          });
+          tabId = result.tabId;
+          return result.snapshot;
+        });
+        void persistWrite(() =>
+          hostClient.browserTabs.openOrFocus.mutate({
+            ...input,
+            tabId: mintedId,
+          }),
+        );
+      }
+      void navigate({
+        to: "/embedded-app",
+        search: { path },
+        state: (prev) => ({ ...prev, tabId }),
+      });
+    },
+    [hostClient, navigate],
+  );
+}
diff --git a/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx b/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
index 991809c8d9..07928df149 100644
--- a/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
+++ b/packages/ui/src/features/embedded-app/EmbeddedAppView.tsx
@@ -1,8 +1,11 @@
 import { useHostTRPC } from "@posthog/host-router/react";
 import { Button } from "@posthog/quill";
+import { useOpenEmbeddedAppTab } from "@posthog/ui/features/browser-tabs/useOpenEmbeddedAppTab";
 import { useQuery } from "@tanstack/react-query";
+import { Plus } from "lucide-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useThemeStore } from "../../shell/themeStore";
+import { normalizeEmbedPath } from "./embeddedAppTab";
 
 /**
  * EXPERIMENT (embedded webapp): renders the real PostHog webapp in an iframe.
@@ -10,8 +13,9 @@ import { useThemeStore } from "../../shell/themeStore";
  * The iframe points at a local main-process proxy that serves the webapp
  * shell and forwards /api to PostHog cloud with the app's OAuth token, so
  * the webapp sees a same-origin cookie-less API. A postMessage bridge keeps
- * navigation and theme in sync (see frontend/src/embed/bridge.ts in the
- * posthog repo).
+ * navigation and theme in sync, and forwards new-tab intents (window.open /
+ * target="_blank" inside the webapp) so they open as host browser tabs
+ * (see frontend/src/embed/bridge.ts in the posthog repo).
  */
 
 const FROM_EMBED = "posthog-embed";
@@ -38,6 +42,7 @@ export function PostHogApp({ url: initialPath }: PostHogAppProps) {
     }),
   );
   const isDarkMode = useThemeStore((s) => s.isDarkMode);
+  const openEmbeddedAppTab = useOpenEmbeddedAppTab();
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const [embedRoute, setEmbedRoute] = useState<string | null>(null);
   const [ready, setReady] = useState(false);
@@ -57,6 +62,17 @@ export function PostHogApp({ url: initialPath }: PostHogAppProps) {
     );
   }, []);
 
+  // Open a webapp path as a NEW host browser tab (or focus the tab already
+  // at that path — tab identity encodes the path).
+  const openHostTab = useCallback(
+    (path: string) => {
+      openEmbeddedAppTab(normalizeEmbedPath(path));
+    },
+    [openEmbeddedAppTab],
+  );
+  const openHostTabRef = useRef(openHostTab);
+  openHostTabRef.current = openHostTab;
+
   // Read inside the message handler without re-subscribing on theme changes.
   const isDarkModeRef = useRef(isDarkMode);
   isDarkModeRef.current = isDarkMode;
@@ -87,6 +103,12 @@ export function PostHogApp({ url: initialPath }: PostHogAppProps) {
         typeof message.url === "string"
       ) {
         setEmbedRoute(message.url);
+      } else if (
+        message.type === "openTab" &&
+        typeof message.url === "string"
+      ) {
+        // window.open / target="_blank" inside the webapp: open a host tab.
+        openHostTabRef.current(message.url);
       }
     };
     window.addEventListener("message", onMessage);
@@ -134,6 +156,15 @@ export function PostHogApp({ url: initialPath }: PostHogAppProps) {
             {link.label}
           </Button>
         ))}
+        <Button
+          variant="outline"
+          size="sm"
+          title="Open the current page in a new tab"
+          onClick={() => openHostTab(embedRoute ?? initialPath)}
+        >
+          <Plus size={14} />
+          New tab
+        </Button>
         <span className="ml-auto truncate font-mono text-xs opacity-60">
           {ready ? (embedRoute ?? "") : "connecting…"}
         </span>
diff --git a/packages/ui/src/features/embedded-app/embeddedAppTab.ts b/packages/ui/src/features/embedded-app/embeddedAppTab.ts
new file mode 100644
index 0000000000..7319a31e3c
--- /dev/null
+++ b/packages/ui/src/features/embedded-app/embeddedAppTab.ts
@@ -0,0 +1,29 @@
+/**
+ * EXPERIMENT (embedded webapp): browser-tab identity for embedded surfaces.
+ *
+ * A tab hosting the embedded PostHog webapp encodes its initial webapp path
+ * into the tab's appView string ("embedded-app:<path>"). The browser-tabs
+ * domain layer treats appView as an opaque string, so distinct paths are
+ * distinct tab identities (dedup/focus works per path) with no schema change.
+ */
+const EMBEDDED_APP_TAB_PREFIX = "embedded-app:";
+
+export function embeddedAppTabView(path: string): string {
+  return `${EMBEDDED_APP_TAB_PREFIX}${path}`;
+}
+
+export function embeddedAppTabPath(appView: string | null): string | null {
+  return appView?.startsWith(EMBEDDED_APP_TAB_PREFIX)
+    ? appView.slice(EMBEDDED_APP_TAB_PREFIX.length)
+    : null;
+}
+
+/**
+ * Normalize a webapp URL into a stable tab path: kea-router prefixes
+ * `/project/<id>` onto every in-app URL, which would make "/notebooks" and
+ * "/project/2/notebooks" two different tab identities for the same surface.
+ */
+export function normalizeEmbedPath(url: string): string {
+  const withoutProject = url.replace(/^\/project\/[^/]+/, "");
+  return withoutProject === "" ? "/" : withoutProject;
+}
diff --git a/packages/ui/src/router/routes/embedded-app.tsx b/packages/ui/src/router/routes/embedded-app.tsx
index 269ef22f48..9e9a987053 100644
--- a/packages/ui/src/router/routes/embedded-app.tsx
+++ b/packages/ui/src/router/routes/embedded-app.tsx
@@ -1,11 +1,23 @@
 import { PostHogApp } from "@posthog/ui/features/embedded-app/EmbeddedAppView";
 import { createFileRoute } from "@tanstack/react-router";
 
-/** EXPERIMENT (embedded webapp): dev route hosting the iframe'd PostHog app. */
+/**
+ * EXPERIMENT (embedded webapp): route hosting the iframe'd PostHog app.
+ * `path` is the webapp path this surface starts at; each distinct path is its
+ * own browser tab (identity is encoded into the tab's appView string, see
+ * BrowserTabStrip).
+ */
 export const Route = createFileRoute("/embedded-app")({
+  validateSearch: (search: Record<string, unknown>): { path?: string } => ({
+    path: typeof search.path === "string" ? search.path : undefined,
+  }),
   component: EmbeddedAppRoute,
 });
 
 function EmbeddedAppRoute() {
-  return <PostHogApp url="/notebooks" />;
+  const { path } = Route.useSearch();
+  const url = path ?? "/notebooks";
+  // Key by path so switching between two embedded tabs remounts the surface
+  // cleanly instead of reusing a stale iframe/bridge pair.
+  return <PostHogApp key={url} url={url} />;
 }
diff --git a/packages/ui/src/router/useAppView.ts b/packages/ui/src/router/useAppView.ts
index 05402a4233..318ad600a6 100644
--- a/packages/ui/src/router/useAppView.ts
+++ b/packages/ui/src/router/useAppView.ts
@@ -20,7 +20,8 @@ export type AppViewType =
   | "skills"
   | "notebooks"
   | "mcp-servers"
-  | "settings";
+  | "settings"
+  | "embedded-app";
 
 export interface AppView {
   type: AppViewType;
@@ -34,9 +35,15 @@ export interface AppView {
   initialMode?: string;
   folderRunEnvironment?: "local" | "cloud";
   reportAssociation?: TaskInputReportAssociation;
+  /** EXPERIMENT (embedded webapp): the webapp path this surface starts at. */
+  embedPath?: string;
 }
 
-type Match = { routeId: string; params: Record<string, string | undefined> };
+type Match = {
+  routeId: string;
+  params: Record<string, string | undefined>;
+  search?: Record<string, unknown>;
+};
 
 function deriveFromMatches(matches: Match[]): AppView {
   const last = matches[matches.length - 1];
@@ -90,6 +97,13 @@ function deriveFromMatches(matches: Match[]): AppView {
     case "/settings/$category":
     case "/settings/":
       return { type: "settings" };
+    case "/embedded-app": {
+      const path = last.search?.path;
+      return {
+        type: "embedded-app",
+        embedPath: typeof path === "string" ? path : undefined,
+      };
+    }
     default:
       if (last.routeId.startsWith("/code/inbox")) {
         return { type: "inbox" };
@@ -123,6 +137,7 @@ export function useAppView(): AppView {
         ? {
             routeId: m.routeId,
             params: m.params as Record<string, string | undefined>,
+            search: m.search as Record<string, unknown>,
           }
         : null;
     },
@@ -133,12 +148,19 @@ export function useAppView(): AppView {
   const taskId = last?.params.taskId;
   const pendingKey = last?.params.key;
   const folderId = last?.params.folderId;
+  const searchPath = last?.search?.path;
+  const embedSearchPath =
+    typeof searchPath === "string" ? searchPath : undefined;
 
   return useMemo(() => {
     // Rebuild the match from primitives so the memo depends only on stable
     // values — the `last` selector returns a fresh object every render.
     const match = routeId
-      ? { routeId, params: { taskId, key: pendingKey, folderId } }
+      ? {
+          routeId,
+          params: { taskId, key: pendingKey, folderId },
+          search: { path: embedSearchPath },
+        }
       : null;
     const view = deriveFromMatches(match ? [match] : []);
 
@@ -157,7 +179,7 @@ export function useAppView(): AppView {
       };
     }
     return view;
-  }, [routeId, taskId, pendingKey, folderId, prefill]);
+  }, [routeId, taskId, pendingKey, folderId, embedSearchPath, prefill]);
 }
 
 /**