Embed the Theo Browser

​

Quick start

1. Create a session from your backend (never expose your THEO_API_KEY to the browser):

import { Theo } from "@hitheo/sdk";
const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

const session = await theo.browser.create({
  url: "https://example.com",
  region: "us-west-2",
});
return Response.json({ embed_url: session.embed_url });

2. Drop the URL into an iframe on your frontend:

<iframe
  src="{embed_url}"
  width="100%"
  height="600"
  allow="clipboard-read; clipboard-write"
  sandbox="allow-scripts allow-same-origin"
></iframe>

• Fetching the correct live view URL on first paint (no about:blank flash)
• Listening for browserbase-disconnected postMessages
• Auto-refetching and rekeying the iframe when the CDP target changes
• Tight 10 s polling while disconnected, relaxed 30 s while healthy
• A Theo-branded URL bar + live indicator + reconnect overlay

​

How the token works

• Format: {APP_ORIGIN}/embed/browser/{sessionId}?token=<hmac>
• Scope: the token is tied to a specific session AND the user who created it
• Lifetime: 60 minutes (Theo Browser sessions hard-cap at 20 min, so this leaves headroom for keep_alive sessions)
• Secret: signed with BROWSER_EMBED_TOKEN_SECRET on the server; never exposed to the client
• Rotation: every GET /api/v1/browser/sessions/:id call mints a fresh token, so long-running dashboards can refresh the iframe on demand

​

Disconnect handling

// Listen on the parent window for the iframe's disconnect event.
window.addEventListener("message", (ev) => {
  if (ev.data === "browserbase-disconnected") {
    // Option A: let Theo handle it — refetch /live?force=1 and rekey.
    // Option B: surface a "reconnecting…" UI to your user.
  }
});

​

Security posture

• Iframe sandbox: allow-scripts allow-same-origin is the minimal set that keeps the DevTools frontend + CDP WebSocket alive. Adding allow-forms / allow-popups has no functional benefit and can trigger stray navigations that retarget the iframe out of the live view.
• frame-ancestors *: the embed page sets Content-Security-Policy: frame-ancestors * so any origin can iframe it. If you want to restrict which origins can load the embed, terminate the iframe at your own CDN layer and apply your own header.
• No credentials in the iframe: the embed page never sees your API key. It talks to a companion token-authenticated /embed/browser/:id/live route.

​

End the session

await theo.browser.end(session.session_id);

​

Related

• Browser Sessions API — the full /api/v1/browser/sessions surface
• Theo Browser SDK — typed helpers for Node/Deno/edge