Skip to main content
Stagehand can remote-control any Chrome session that exposes a CDP endpoint. Hyperbrowser supplies the always-on, privacy-hardened sessions—complete with stealth, proxies, ad blocking, and observability—so you can connect Stagehand to a reliable browser in seconds without standing up Chrome yourself.

​
Why Hyperbrowser for your Stagehand project?

  • Consistent environments – launch Chrome with stealth, custom profiles, and residential/static proxies through a single API call.
  • Enterprise controls – restrict egress with managed proxies, enable audit logs via recordings/download inspection, and reuse sessions for multi-step flows.
  • Faster swaps – migrate existing Browserbase + Stagehand projects by replacing the session creation call; the Stagehand client still points to the CDP URL it receives.
  • Live debugging – every session automatically exposes liveUrl, letting you watch Stagehand steps in real time.

​
Prerequisites

  1. HYPERBROWSER_API_KEY loaded via .env or your secret manager.
  2. Access to Stagehand via @browserbasehq/stagehand (or clone from docs.stagehand.dev).

​
Installation

npm install @hyperbrowser/sdk @browserbasehq/stagehand dotenv

​
Quickstart (TypeScript)

This example mirrors the reference gist and shows Stagehand driving a Hyperbrowser session. It enables stealth, ad blocking, and accepts cookies out of the box, then attaches Stagehand to the returned CDP endpoint. To see all the available session parameters, check out the Session Parameters page.
This example uses the new Stagehand v3 implementation.
import { config } from "dotenv";
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { Stagehand } from "@browserbasehq/stagehand";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function main() {
  const session = await client.sessions.create({
    useStealth: true,
    adblock: true,
    acceptCookies: true,
  });

  console.log(`Watch live: ${session.liveUrl}`);

  const stagehand = new Stagehand({
    env: "LOCAL",
    localBrowserLaunchOptions: {
      cdpUrl: session.wsEndpoint,
    },
  });

  try {
    await stagehand.init();
    const page = stagehand.context.pages()[0];
    await page.goto("https://hyperbrowser.ai");
    await stagehand.act("Click on the 'Launch Browser' button");
    console.log("Page title:", await page.title());
    console.log("Waiting 5 seconds before closing");
    await sleep(5_000);
  } catch (err) {
    console.error("Stagehand task failed:", err);
  } finally {
    await stagehand.close();
    await client.sessions.stop(session.id);
  }
}

main().catch((error) => {
  console.error("Stagehand task failed:", error);
  process.exit(1);
});

​
Switch from Browserbase

Browserbase setupHyperbrowser replacement
const session = await browserbase.sessions.create({...});const session = await hyperbrowser.sessions.create({...});
session.connectUrlsession.wsEndpoint
liveViewLinks.debuggerFullscreenUrlsession.liveUrl
BROWSERBASE_API_KEYHYPERBROWSER_API_KEY
Migration checklist from Browserbase to Hyperbrowser
  • Swap the SDK import to @hyperbrowser/sdk.
  • Rename environment variables and CI secrets to HYPERBROWSER_API_KEY.
  • Map Browserbase session flags to Hyperbrowser equivalents (stealth, proxies, uploads, downloads, custom extensions).
  • Update dashboards/links to use session.liveUrl.
  • Stop sessions explicitly with client.sessions.stop(session.id) to free capacity when Stagehand finishes.

​
Troubleshooting & resources