What is the intended approach to having multiple, concurrent Stagehand sessions running from within one (async) app?

[mikenerone]

I want to run multiple Stagehand sessions from one (async) application. This is easy to do with Playwright (from a singleton AsyncPlaywright instance, you can create as many Browser instances as you like via launch() or connect_over_cdp()). Everything in Playwright (even AsyncPlaywright itself) is designed to be ephemeral. But there are conflicting signals about how to accomplish this with Stagehand:

Aspects that suggest you're supposed to have a singleton Stagehand instance:

1. The underlying AsyncPlaywright is normally a singleton, so the fact that init() creates and manages that instance gives the expectation that it's also a singleton.
2. When using Stagehand with Browserbase, and using the python browserbase client, you can, indeed, easily create as many sessions as you like This suggests the intent to support many sessions, so one would expect your own Stagehand client to be able to use them.
3. Stagehand.__init__() installs its own signal handlers for the application. Setting aside the fact that libraries should not do this at all (because app developers may set their own signal handlers for a variety of reasons and you should not overwrite them; of course doing it for the separate browser process when running locally would be understandable, but that's not what happens here), it's certainly something you wouldn't do repeatedly. This one seems completely at odds with having multiple instances.

Aspects that suggest you're meant to make a separate Stagehand instance for each browser session:

1. It accepts all of the browser launch arguments up front, as if there's only one set of them. (If this is just a case of providing a shortcut for the simple one-session case, that's fine, if a little confusing.)
2. The class has the concept of a current page via the LivePageProxy. This is completely at odds with having only a single instance when using multiple sessions.

I guess the example I'd ask for is:

1. Start three different, concurrent Browserbase sessions with the browserbase client.
2. Start a stagehand client for each of them, visiting three different URLs, however that's intended to look. I'd really like to see this with pre-created sessions similar to how one would normally use Browserbase with Playwright, rather than let the Stagehand wrapper abstract away the session creation.

[rsbryan]

Hey Mike,

Running multiple Stagehand/Browserbase sessions concurrently

TL;DR

• Treat Stagehand instances as per-session, not a global singleton.
• Use one Playwright connection per Browserbase session; reuse the default context & page provided by Browserbase.
• You can spin up multiple concurrent sessions and drive them independently.

Why

Browserbase supports many sessions (via bb.sessions.create + CDP).

Docs emphasize using the default context/page (don’t create new ones).

Signal handlers in Stagehand.init() make a single Stagehand-per-process awkward; avoid global, prefer one Stagehand client per session.

Minimal example (ts)

import Browserbase from "@browserbasehq/sdk";
import { chromium, Browser } from "playwright-core";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function connectSession(projectId?: string) {
  const session = await bb.sessions.create({ projectId: projectId ?? process.env.BROWSERBASE_PROJECT_ID! });
  const browser: Browser = await chromium.connectOverCDP(session.connectUrl);

  // Use Browserbase-provided default context/page
  const ctx = browser.contexts()[0];
  const page = ctx.pages()[0] ?? (await ctx.newPage());

  // Optional: live view URL
  const { debuggerUrl } = await bb.sessions.debug(session.id);
  console.log("Live view:", debuggerUrl);

  return { sessionId: session.id, browser, page };
}

(async () => {
  const runs = await Promise.all([1, 2, 3].map(() => connectSession()));

  await Promise.all(
    runs.map(({ page }, i) =>
      page.goto(`https://example.com?sid=${i + 1}`, { waitUntil: "domcontentloaded" })
    )
  );

  // …interact as needed…

  // Cleanly close to finalize artifacts
  await Promise.all(runs.map(({ browser }) => browser.close()));
})();

[mikenerone]

Wow, now it hits me that I barely mentioned that I was speaking in reference to Stagehand in Python. I should have been much clearer. It's the Python library that I feel is not conducive to multiple instances (because of things like every instance installing overwriting signal handlers and each instance creating its own (normally singleton) AsyncPlaywright instance).