What is Stagehand?
Stagehand is a framework for building browser automation applications. Pairing it with a remote runtime means the application and browser can run in different environments. The browser still needs to meet the requirements of the Stagehand version in use.
This collection covers the v4 attachment model in the official browser configuration. For v4, a CDP URL is part of the setup, but extension availability also matters.
Why consider a remote runtime?
A separate browser service can move browser process operations, account storage, and observation away from an application worker. Evaluate the combination against your real workload: page inspection, navigation, authenticated state, and any file transfer the application requires.
Make the compatibility check an explicit deployment step. A successful transport connection is weaker evidence than an application action completing with the correct result.
Quick start
Stagehand v4 discovers an installed Stagehand extension when connecting. If it needs to load the bundled extension, loading requires a shared filesystem. A hosted browser on another machine may not share the application's filesystem. Confirm extension provisioning with the runtime operator before using the attachment snippet.
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
const browser = await localBrowser.connect({
cdpUrl: process.env.REMOTE_BROWSER_CDP_URL!,
});
const stagehand = await Stagehand.create({ browser });This is the upstream configuration shape, conditional on those runtime requirements. It is not an end-to-end Remote Browser compatibility certification. Pin the SDK version and validate the endpoint before starting your application.
Connection methods and prerequisites
Check which address each component can reach. The application can reach a public gateway while a browser-side component has a different route. Stagehand's documentation describes authentication headers and an optional separate extension CDP URL for this arrangement. Ask the runtime operator to verify the topology rather than guessing internal endpoints.
For an existing browser, plan provider-side allocation release separately from the framework connection lifecycle. Preserve the allocation identifier so your application can reconcile abandoned work after a crash.
Use cases to validate
- A containerized application whose browser runs in another environment.
- Authorized account workflows using a provider-managed profile.
- Browser tasks with an observer who can assist at login renewal.
- Applications that need evidence and checkpointing across worker failures.
For each case, test the exact browser, extension, gateway, and SDK versions together. Include downloads and uploads when those are part of the task. Do not infer filesystem interoperability from a successful page load.
FAQ
Does any CDP endpoint automatically satisfy Stagehand v4?
No. Verify extension discovery or provisioning and its connectivity, as well as the application-side connection.
Should I copy a v3 connection example into a v4 project?
Use the documentation for the pinned major version. Connection and initialization code should be reviewed as part of an upgrade.
Is there a measured Stagehand speed result here?
No Stagehand-specific result is published in this collection. The benchmark resource below provides a browser-path baseline; an application benchmark also needs the framework actions and a task-level success condition.