Feature Request: Add `port` option to `LocalBrowserLaunchOptions` for fixed CDP debugging port

[sashank-zluri]

Problem

When using Stagehand V3 in LOCAL mode, the Chrome DevTools Protocol (CDP) debugging port is randomly assigned each time the browser launches. This makes it impossible to:

• Connect external debugging tools to a fixed port
• Configure chrome://inspect with a persistent port
• Set up development workflows that rely on a known port

Current Behavior

• Passing --remote-debugging-port=9222 in localBrowserLaunchOptions.args is ignored because Stagehand internally calls getRandomPort() and adds its own --remote-debugging-port=${randomPort} flag
• The only workaround is to launch Chrome manually and use cdpUrl to connect

Expected Behavior

Allow users to specify a fixed debugging port via localBrowserLaunchOptions.port:

const stagehand = new Stagehand({
    env: "LOCAL",
    localBrowserLaunchOptions: {
        headless: true,
        port: 9222,  // <-- New option to pin the debugging port
    },
    model: "openai/gpt-4o",
});

Technical Details

Looking at the source code in dist/index.js:

1. Line 35781: requestedPort defaults to 0

   this.requestedPort = defaults(this.opts.port, 0);

2. Line 35909: If requestedPort === 0, a random port is assigned

   this.port = yield getRandomPort();

3. Line 64707: User args are added, but Stagehand's random port takes precedence

   if (Array.isArray(lbo.args)) chromeFlags.push(...lbo.args);

The internal port option exists but is not exposed through LocalBrowserLaunchOptions.

Proposed Solution

Add port to the LocalBrowserLaunchOptions interface and pass it through to the Chrome launcher:

interface LocalBrowserLaunchOptions {
  // ... existing options
  port?: number;  // Fixed CDP debugging port
}

Environment

• Stagehand version: 3.0.6
• OS: macOS

[dhanushchalicheemala]

Hi @sashank-zluri! I'd like to work on this feature.

Are you already working on this issue, or should I go ahead and tackle it?

If you're not actively working on it, I'm happy to submit a PR. The solution looks straightforward based on your analysis - exposing the existing port option through LocalBrowserLaunchOptions and passing it to the Chrome launcher.

Let me know!