[docs]: add docs for local browser port option

[seanmcguire12]

why

Missing docs for local browser port

what changed

Add documentation for the port option in LocalBrowserLaunchOptions that was added in PR #1575. This option allows users to specify a fixed Chrome CDP debugging port instead of using a randomly assigned port.

Updated:

• packages/docs/v3/references/stagehand.mdx - Added port parameter to LocalBrowserLaunchOptions documentation
• packages/docs/v3/configuration/browser.mdx - Added port to example and new "Fixed CDP Debugging Port" section explaining the feature # test plan

---

Summary by cubic

Document the port option in LocalBrowserLaunchOptions so users can set a fixed Chrome DevTools Protocol debugging port. Adds examples and guidance (including a 9222 tip) in the configuration and API reference pages.

^{Written for commit 17104a6. Summary will update on new commits. Review in cubic}

---

why

what changed

test plan

[changeset-bot]

⚠️ No Changeset found

Latest commit: 17104a6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[cubic-dev-ai]

No issues found across 2 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User
    participant SDK as Stagehand SDK
    participant Chrome as Chrome Process

    Note over User,Chrome: Runtime flow for the documented "port" option

    User->>SDK: new Stagehand({ localBrowserLaunchOptions: { port: 9222 } })
    User->>SDK: init()

    SDK->>SDK: Parse launch options
    
    Note right of SDK: Maps "port" option to<br/>--remote-debugging-port=9222

    SDK->>Chrome: Spawn process with args
    
    alt Port 9222 Available
        Chrome->>Chrome: Listen on localhost:9222
        Chrome-->>SDK: PID / Process Started
        SDK->>Chrome: Connect via CDP (ws://localhost:9222)
        Chrome-->>SDK: Connection Established
        SDK-->>User: Ready
    else Port In Use (Documented Edge Case)
        Chrome-->>SDK: Process Error/Exit
        SDK-->>User: Error: Connection failed
    end

Loading

[greptile-apps]

Greptile Overview

Greptile Summary

Documents the port option in LocalBrowserLaunchOptions allowing users to specify a fixed Chrome DevTools Protocol debugging port instead of a randomly assigned one.

Changes:

• Added port: 9222 to the local browser configuration example in browser.mdx:189
• Created new "Fixed CDP Debugging Port" section with standalone example and tip about port 9222 being the standard CDP default
• Added port parameter documentation in the API reference under LocalBrowserLaunchOptions with type, description, and default value

The documentation accurately reflects the implementation added in PR #1575, where the port option is passed through V3Options → LocalBrowserLaunchOptions → launchLocalChrome → chrome-launcher's launch() function.

Confidence Score: 5/5

• This documentation PR is safe to merge with no issues
• Perfect documentation changes that accurately document the existing port option from PR [feat]: add configurable local CDP debugging port #1575. The documentation is consistent across both files, includes helpful examples and tips, and matches the actual implementation in the codebase
• No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/configuration/browser.mdx	Added port parameter documentation to local browser configuration example and created new "Fixed CDP Debugging Port" section with usage example and tip about port 9222
packages/docs/v3/references/stagehand.mdx	Added port parameter to LocalBrowserLaunchOptions documentation with description and default value (randomly assigned)

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant V3
    participant launchLocalChrome
    participant ChromeLauncher
    participant Chrome

    User->>Stagehand: new Stagehand({env: "LOCAL", localBrowserLaunchOptions: {port: 9222}})
    User->>Stagehand: await stagehand.init()
    Stagehand->>V3: init() with localBrowserLaunchOptions
    V3->>V3: Process launch options (flags, viewport, etc.)
    V3->>launchLocalChrome: launchLocalChrome({port: 9222, chromeFlags, ...})
    launchLocalChrome->>ChromeLauncher: launch({port: 9222, ...})
    ChromeLauncher->>Chrome: Start Chrome with --remote-debugging-port=9222
    Chrome-->>ChromeLauncher: Chrome process started
    ChromeLauncher-->>launchLocalChrome: Chrome instance with fixed port
    launchLocalChrome->>launchLocalChrome: waitForWebSocketDebuggerUrl(9222)
    launchLocalChrome-->>V3: {ws: "ws://127.0.0.1:9222/...", chrome}
    V3->>V3: Create V3Context with CDP WebSocket URL
    V3-->>Stagehand: Browser initialized
    Stagehand-->>User: Ready for automation

Loading

[greptile-apps]

_{No files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}