[feat]: add configurable local CDP debugging port

[seanmcguire12]

this PR was opened on behalf of @dhanushchalicheemala. thanks for the contribution!!

why :

In env: "LOCAL" mode, Stagehand always launches Chrome on a random CDP debugging port. This makes it hard to attach external tools or configure chrome://inspect with a fixed port.

what changed :

• Add an optional port?: number to LocalBrowserLaunchOptions.
• Thread this value through to the local Chrome launcher and pass it as the port option to chrome-launcher.
• Update V3 docs to document localBrowserLaunchOptions.port.

Usage

const stagehand = new Stagehand({
env: "LOCAL", localBrowserLaunchOptions: { headless: true, port: 9222, }, model: "openai/gpt-4.1-mini", });

Test plan

• pnpm --filter @browserbasehq/stagehand run build
• pnpm --filter @browserbasehq/stagehand lint (passes)
• pnpm --filter @browserbasehq/stagehand test:vitest

---

Summary by cubic

Adds an optional localBrowserLaunchOptions.port to pin the local Chrome CDP debugging port in LOCAL mode. This makes it easy to attach external tools or use chrome://inspect with a fixed port, while keeping the default random port if unset.

• New Features
  • Added port?: number to LocalBrowserLaunchOptions and passed it through launchLocalChrome to chrome-launcher.

^{Written for commit d7d2233. Summary will update on new commits.}

---

why

what changed

test plan

[changeset-bot]

🦋 Changeset detected

Latest commit: d7d2233

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

No issues found across 4 files

[greptile-apps]

Greptile Summary

This PR adds an optional port parameter to LocalBrowserLaunchOptions, allowing users to specify a fixed CDP debugging port when running Stagehand in LOCAL mode. Previously, Chrome always launched on a random port, making it difficult to attach external debugging tools or configure chrome://inspect with a fixed address.

Key Changes:

• Added port?: number to the Zod schema for LocalBrowserLaunchOptions in packages/core/lib/v3/types/public/api.ts:23
• Threaded the port value through the internal LaunchLocalOptions interface in packages/core/lib/v3/launch/local.ts:9
• Passed the port option to chrome-launcher in packages/core/lib/v3/launch/local.ts:30 and packages/core/lib/v3/v3.ts:835
• Updated documentation to describe the new parameter and its use case

The implementation is clean and follows the existing pattern for optional configuration parameters. The change is backward compatible (defaults to random port when unspecified) and properly validated by the Zod schema.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is straightforward, follows existing patterns, and adds an optional feature without breaking existing functionality. The change properly threads a single optional parameter through the call stack to the underlying chrome-launcher library, which already supports this option. All changes maintain type safety via Zod schemas, and documentation is included.
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/lib/v3/launch/local.ts	Added optional port parameter to LaunchLocalOptions interface and passed it to chrome-launcher
packages/core/lib/v3/types/public/api.ts	Added optional port: z.number().optional() field to LocalBrowserLaunchOptionsSchema
packages/core/lib/v3/v3.ts	Threaded port option from localBrowserLaunchOptions to launchLocalChrome call
packages/docs/v3/references/stagehand.mdx	Documented the new port parameter with usage instructions and chrome://inspect reference

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant V3
    participant launchLocalChrome
    participant ChromeLauncher

    User->>Stagehand: new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { port: 9222 } })
    User->>Stagehand: init()
    Stagehand->>V3: constructor with options
    V3->>V3: Extract localBrowserLaunchOptions.port
    V3->>launchLocalChrome: launchLocalChrome({ port: 9222, ... })
    launchLocalChrome->>ChromeLauncher: launch({ port: 9222, ... })
    ChromeLauncher-->>launchLocalChrome: chrome instance with fixed port
    launchLocalChrome->>launchLocalChrome: waitForWebSocketDebuggerUrl(chrome.port)
    launchLocalChrome-->>V3: { ws, chrome }
    V3-->>Stagehand: initialized
    Note over User,ChromeLauncher: Chrome now listens on port 9222 for debugging

Loading