feat(cli): expose local browser launch options in browse driver

[optimusbuilder]

why

The browse CLI managed-local mode had no way to pass Chrome path, connect timeout, or custom Chrome args — unlike the SDK's localBrowserLaunchOptions.

what changed

• Add --chrome-path, --connect-timeout, and repeatable --chrome-arg flags
• Wire flags through session-manager to Stagehand launch options
• Extend browse doctor to verify Chrome executable for managed-local mode
• Unit tests for flag wiring and doctor checks

test plan

• pnpm --filter browse exec vitest run tests/local-launch-flags.test.ts tests/launch-options.test.ts tests/doctor.test.ts

Depends on PR2 merging first (or rebase after merge).

---

Summary by cubic

Expose local Chrome launch controls in the browse CLI and make local launches more reliable by validating the Chrome executable and honoring user-supplied Chromium flags. Clarify docs for ignoreDefaultArgs so behavior is predictable.

• New Features

  • Add --chrome-path, --connect-timeout, and repeatable --chrome-arg for managed-local mode.
  • Wire flags through the session manager to localBrowserLaunchOptions in @browserbasehq/stagehand.
  • browse doctor checks the Chrome path (including CHROME_PATH) and reports launch details.

• Bug Fixes

  • Stop forcing --site-per-process in local launches so --disable-features=site-per-process and --renderer-process-limit work as expected.
  • Support chromiumSandbox: false by adding --no-sandbox and --disable-setuid-sandbox when requested.
  • Share default Chrome flags via STAGEHAND_DEFAULT_FLAGS and clarify docs that ignoreDefaultArgs: true removes both chrome-launcher defaults and STAGEHAND_DEFAULT_FLAGS, plus site-isolation guidance.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 2257434

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-v3	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

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

1 issue found across 22 files

Confidence score: 4/5

• This PR looks generally safe to merge, with risk centered on a documentation/behavior mismatch rather than a direct runtime code break.
• The most significant issue is in packages/docs/v3/configuration/browser.mdx: it says ignoreDefaultArgs: true keeps Stagehand flags, but implementation removes STAGEHAND_DEFAULT_FLAGS (like --remote-allow-origins=* and --no-first-run), which could mislead users configuring browser launch options.
• Because the issue is user-facing docs accuracy (severity 6/10, confidence 8/10) and not a clear functional regression in app logic, the overall merge risk stays moderate-low.
• Pay close attention to packages/docs/v3/configuration/browser.mdx - clarify ignoreDefaultArgs behavior so users understand Stagehand default flags are removed.

Architecture diagram

sequenceDiagram
    participant CLI as browse CLI (commands/open.ts)
    participant Flags as Flags Parser (flags.ts)
    participant ModeResolver as Mode Resolver (mode.ts)
    participant ChromePathResolver as Chrome Path Resolver (chrome-path.ts)
    participant Doctor as Doctor (doctor.ts)
    participant SessionManager as Session Manager (session-manager.ts)
    participant LaunchOptionsBuilder as Launch Options Builder (launch-options.ts)
    participant StagehandCore as @browserbasehq/stagehand (core)

    Note over CLI,StagehandCore: Managed-local browser launch flow

    CLI->>Flags: Parse --chrome-path, --connect-timeout, --chrome-arg
    CLI->>ModeResolver: resolveConnectionTarget(flags)

    ModeResolver->>ModeResolver: failOnConflictingLocalLaunchFlags()
    alt Conflicting flags (--chrome-path + --cdp)
        ModeResolver-->>CLI: Throw error
    else No conflict
        ModeResolver->>ModeResolver: resolveManagedLocalLaunch()
        ModeResolver->>ChromePathResolver: resolveChromeExecutablePath(explicit?, env?)
        ChromePathResolver->>ChromePathResolver: Check explicit path, CHROME_PATH, defaults
        ChromePathResolver-->>ModeResolver: executable path or undefined
        ModeResolver-->>CLI: ConnectionTarget { kind: "managed-local", launch: {...} }
    end

    Note over Doctor,ModeResolver: Doctor check for managed-local

    Doctor->>ChromePathResolver: resolveChromeExecutablePath(explicit?, env?)
    alt No executable found
        Doctor-->>CLI: { status: "fail", message: "no Chrome executable found" }
    else Executable found
        Doctor-->>CLI: { status: "ok", message: "managed local browser, ...", details: {...} }
    end

    Note over SessionManager,StagehandCore: Session initialization

    SessionManager->>LaunchOptionsBuilder: buildManagedLocalLaunchOptions(target.launch)
    LaunchOptionsBuilder->>LaunchOptionsBuilder: Map executablePath, connectTimeoutMs, args
    LaunchOptionsBuilder-->>SessionManager: LocalBrowserLaunchOptions
    SessionManager->>StagehandCore: init({ localBrowserLaunchOptions: {...} })

    Note over StagehandCore: Launch configuration (core/lib/v3/launch/local.ts)

    StagehandCore->>StagehandCore: Build chrome-launcher args from STAGEHAND_DEFAULT_FLAGS + user args
    opt chromiumSandbox === false
        StagehandCore->>StagehandCore: Append --no-sandbox, --disable-setuid-sandbox
    end
    StagehandCore->>StagehandCore: Launch Chrome with resolved flags

Loading

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

Fix all with cubic | Re-trigger cubic</sub>

[optimusbuilder]

The docs issue was in browser.mdx from the stacked PR2 changes , now fixed in 2257434. Clarifies that ignoreDefaultArgs: true removes both chrome-launcher and Stagehand default flags.