[seanmcguire12]

Why

Stagehand's extension opens its own CDP connection to the browser, and it is handed the URL the Python client connected with. That only works when the client and the browser can use the same address.

Sometimes they can't. Our case: the client runs in a server process and reaches a sandboxed Chrome through an authenticated gateway, wss://<gateway>/.../cdp?api_key=.... The extension, running inside that Chrome, should dial the browser's local endpoint (ws://127.0.0.1:<port>/devtools/browser/<id>). Using the gateway URL would hand the gateway's credentials to the browser, which loads arbitrary pages, and send every extension command out and back in through the gateway. Today the only workaround is overriding the private Stagehand._worker_init_params.

What

browser = await local_browser.connect(
    cdp_url="wss://gateway/cdp?api_key=...",
    extension_cdp_url="ws://127.0.0.1:9300/devtools/browser/<id>",
)
stagehand = await Stagehand.create(browser=browser)

• local_browser.connect takes an optional extension_cdp_url, which must be a ws:// or wss:// URL with a host.
• It is carried on the claimed browser's worker metadata, and Stagehand.create sends it as the init param browser_cdp_url in place of the client's URL.
• When it is unset, behaviour is unchanged.
• Python SDK only, with a minor changeset. The TypeScript SDK has the same assumption and could take the same option; happy to follow up.

Tests

• New tests cover the init param, connect carrying the value through, the default, and rejection of non-WebSocket URLs.
• ruff format --check, ruff check, ty check and generate.py --check pass.
• pytest: 793 passed. test_official_api_routes_through_and_never_closes_a_caller_http_client fails with and without this change in my checkout, because it needs the extension built in packages/extension/dist.

🤖 Generated with Claude Code

---

Summary by cubic

Adds an optional extension_cdp_url to local_browser.connect in the Python SDK so Stagehand's extension can dial a different CDP WebSocket than the client's, when the client reaches Chrome through a proxy or gateway the extension cannot use.

• When set, Stagehand.create sends it as the init param browser_cdp_url in place of the client's URL; when unset, behavior is unchanged.
• The value must be a ws:// or wss:// URL with a host; invalid schemes, ports (including 0), or missing hostnames raise a validation error.
• Python SDK only, with a minor changeset; the TypeScript SDK could take the same option in a follow-up.
• New tests cover the init param, metadata carrying the value through, the default, and rejection of invalid URLs. pytest reports 793 passed; test_official_api_routes_through_and_never_closes_a_caller_http_client fails with and without this change because it needs the extension built in packages/extension/dist.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 48a3789

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

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/stagehand-python	Minor

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]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files

Architecture diagram

sequenceDiagram
    participant Client as Python Client
    participant Connect as local_browser.connect()
    participant Validate as URL Validator
    participant Browser as StagehandBrowser
    participant Stagehand as Stagehand.create()
    participant Ext as Browser Extension

    Note over Client,Ext: Browser Connection with Optional Extension CDP URL

    Client->>Connect: connect(cdp_url, extension_cdp_url?)
    
    alt extension_cdp_url provided
        Client->>Validate: Validate extension_cdp_url
        alt Valid ws:// or wss:// URL
            Validate-->>Connect: Valid URL
        else Invalid URL format
            Validate-->>Connect: ValidationError
            Connect-->>Client: Raise error
        end
        Connect->>Browser: Attach metadata (browser_cdp_url = extension_cdp_url)
    else No extension_cdp_url
        Connect->>Browser: Attach metadata (browser_cdp_url = None)
    end

    Client->>Stagehand: Stagehand.create(browser)
    
    alt browser_cdp_url is set
        Stagehand->>Ext: Send browser_cdp_url as init param
        Note over Stagehand,Ext: Extension dials local CDP endpoint
    else browser_cdp_url is None
        Stagehand->>Ext: Use client's web_socket_debugger_url
        Note over Stagehand,Ext: Extension uses same URL as client
    end

    Ext->>Ext: Connect to CDP WebSocket
    Ext-->>Stagehand: Extension ready
    Stagehand-->>Client: Stagehand instance

Loading

<sub>Requires human review: Auto-approval blocked because this review re-detected 1 unresolved issue already reported by Cubic.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>