Puppeteer

Pass a session's connectUrl as browserWSEndpoint and Puppeteer treats the BrowserGen browser like any remote Chrome. Use puppeteer-core: no local Chromium download needed.

Connect

puppeteer.ts
import puppeteer from "puppeteer-core";

const BROWSERGEN_KEY = process.env.BROWSERGEN_KEY!;

// 1. Create a session over REST.
const session = await fetch("https://api.browsergen.com/v8/web/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${BROWSERGEN_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ timeout: 1800 }),
}).then((r) => r.json());

// 2. Attach Puppeteer to the running browser.
const browser = await puppeteer.connect({
  browserWSEndpoint: session.connectUrl,
});

// 3. Drive the existing page.
const [page] = await browser.pages();
await page.goto("https://example.com");
console.log(await page.title());

// 4. Detach. The session ends ~2 minutes after the last client leaves.
await browser.disconnect();
  • Prefer disconnect() over close(). browser.close() would shut Chromium down inside the session; disconnect()leaves it to BrowserGen's lifecycle (2-minute grace after the last client, then the session ends and is billed no further concurrency).
  • The discovery form works too. Tools that insist on an HTTP endpoint can fetch /json/version on the session host with the same token; the returned webSocketDebuggerUrl is the public connect URL.

Stopping a session immediately

When a job finishes early, free the concurrency slot right away instead of waiting out the grace period:

stop.ts
await fetch(`https://api.browsergen.com/v8/web/sessions/${session.id}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${BROWSERGEN_KEY}` },
});

Related

REST API referenceSession parameters and response fields.AI agentsSessions as tools in an agent loop.