[STG-1808] Use STAGEHAND_API_URL for Stagehand API client by monadoid · Pull Request #2040 · browserbase/stagehand

monadoid · 2026-04-24T18:37:01Z

why

Stagehand should standardize public docs and runtime overrides on STAGEHAND_API_URL without breaking users who still export STAGEHAND_BASE_URL.

what changed

Prefer STAGEHAND_API_URL, with STAGEHAND_BASE_URL as a deprecated legacy fallback.
Emit a one-time deprecation warning when the legacy fallback is used.
Update server-v3 test env plumbing, CI, and docs to use STAGEHAND_API_URL.
Add patch changesets for core and server-v3.

const configuredBaseUrl =
  process.env.STAGEHAND_API_URL ?? process.env.STAGEHAND_BASE_URL;

test plan

pnpm --filter @browserbasehq/stagehand run build:esm
pnpm --filter @browserbasehq/stagehand run test:core -- packages/core/dist/esm/tests/unit/api-optional-model-api-key.test.js
pnpm --filter @browserbasehq/stagehand run typecheck
pnpm --filter @browserbasehq/stagehand-server-v3 run typecheck
pnpm --filter @browserbasehq/stagehand run lint
pnpm --filter @browserbasehq/stagehand-server-v3 run lint
pnpm exec prettier --check .changeset/rude-tips-check.md .github/workflows/ci.yml packages/docs/v3/sdk/java.mdx packages/docs/v3/sdk/python.mdx turbo.json
pnpm changeset status --since origin/main --verbose

changeset-bot · 2026-04-24T18:37:08Z

🦋 Changeset detected

Latest commit: ab2ab29

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

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v4	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

1 issue found across 6 files

Confidence score: 3/5

There is a concrete regression risk in packages/core/lib/v3/api.ts: base-URL precedence behavior in the Stagehand REST API client appears to have changed, which can misroute requests or alter client/server interaction in user-facing flows.
The issue is medium severity (6/10) with high confidence (8/10), and the noted requirement for an integration test under packages/server/test was not met, so impact is not well bounded yet.
Given the behavior change plus missing integration coverage for a breaking-surface area, this is not fully merge-blocking but carries meaningful uncertainty.
Pay close attention to packages/core/lib/v3/api.ts and packages/server/test - verify base-URL precedence remains backward-compatible and add an integration test to lock expected client/server behavior.

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/api.ts">

<violation number="1" location="packages/core/lib/v3/api.ts:867">
P2: Custom agent: **Any breaking changes to Stagehand REST API client / server implementation must be covered by an integration test under packages/server/test**

API client base-URL precedence behavior changed without corresponding server integration-test coverage required by the custom rule.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant App as User Application
    participant Client as StagehandAPIClient
    participant Env as process.env
    participant Log as Logger
    participant API as Stagehand API Server

    Note over App,API: Client Initialization & Base URL Resolution

    App->>Client: new StagehandAPIClient()
    
    Client->>Env: NEW: Check STAGEHAND_BASE_URL
    
    alt STAGEHAND_BASE_URL is present
        Env-->>Client: base_url_value
    else STAGEHAND_BASE_URL is missing
        Client->>Env: CHANGED: Fallback to STAGEHAND_API_URL (Legacy)
        Env-->>Client: api_url_value
        
        opt First time legacy URL is used
            Client->>Log: NEW: Emit deprecation warning (Level 0)
        end
    end

    Note over Client: URL Normalization
    Client->>Client: Strip trailing slashes
    opt Suffix check
        Client->>Client: Append "/v1" if missing
    end

    Note over App,API: Request Flow

    App->>Client: init() / createSession()
    Client->>API: fetch(normalized_url + "/sessions/start")
    API-->>Client: Session Data
    Client-->>App: Response

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

cubic-dev-ai · 2026-04-27T16:50:59Z

@@ -186,6 +186,7 @@ export class StagehandAPIClient {
  private serverCache: boolean;


P2: Custom agent: Any breaking changes to Stagehand REST API client / server implementation must be covered by an integration test under packages/server/test

API client base-URL precedence behavior changed without corresponding server integration-test coverage required by the custom rule.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/core/lib/v3/api.ts, line 867: <comment>API client base-URL precedence behavior changed without corresponding server integration-test coverage required by the custom rule.</comment> <file context> @@ -861,11 +862,27 @@ export class StagehandAPIClient { - // Use STAGEHAND_API_URL env var if set, otherwise use region-based URL + // Use STAGEHAND_BASE_URL when set. STAGEHAND_API_URL is a legacy alias. // Ensure /v1 suffix is present for consistency + const configuredBaseUrl = + process.env.STAGEHAND_BASE_URL ?? process.env.STAGEHAND_API_URL; + if ( </file context>

cubic-dev-ai

1 issue found across 9 files

Confidence score: 4/5

This PR looks safe to merge overall, with a localized configuration fallback mismatch rather than a broad functional risk.
In packages/core/lib/v3/api.ts, using ?? can treat STAGEHAND_API_URL="" as a set value, which may skip STAGEHAND_BASE_URL and lead to unexpected endpoint resolution in common .env setups.
The issue is moderate (5/10 severity, 7/10 confidence) and appears straightforward to fix by aligning the operator with the warning/fallback intent.
Pay close attention to packages/core/lib/v3/api.ts - ensure empty-string env values correctly fall back to the base URL.

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/core/lib/v3/api.ts">

<violation number="1" location="packages/core/lib/v3/api.ts:868">
P2: Use `||` instead of `??` so the fallback semantics match the warning condition. With `??`, an empty `STAGEHAND_API_URL=""` (common in .env files to "unset" a var) prevents `STAGEHAND_BASE_URL` from being used as a fallback, and the deprecation warning fires spuriously.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant App as Developer Application
    participant Env as process.env
    participant Client as StagehandAPIClient
    participant Log as Logger
    participant API as Stagehand API

    Note over App, API: Runtime API Base URL Resolution

    App->>Client: new StagehandAPIClient(config)
    
    Client->>Env: CHANGED: Get STAGEHAND_API_URL
    Env-->>Client: value (or undefined)
    
    alt STAGEHAND_API_URL is missing
        Client->>Env: CHANGED: Get STAGEHAND_BASE_URL (fallback)
        Env-->>Client: value
        
        opt STAGEHAND_BASE_URL is present
            Client->>Log: NEW: emitDeprecationWarning("config", level 0)
            Note right of Log: Only logged once per client instance
        end
    end

    App->>Client: init(modelConfig)
    
    Client->>Client: CHANGED: Normalize URL (trim slashes, ensure /v1)
    
    Client->>API: POST [baseUrl]/v1/sessions/start
    
    alt API Request Success
        API-->>Client: 200 OK (sessionData)
        Client-->>App: Initialization Complete
    else API Request Failure
        API-->>Client: Error Response
        Client-->>App: throw Error
    end

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

cubic-dev-ai · 2026-04-30T17:49:12Z

+    // Use STAGEHAND_API_URL when set. STAGEHAND_BASE_URL is a legacy alias.
    // Ensure /v1 suffix is present for consistency
+    const configuredBaseUrl =
+      process.env.STAGEHAND_API_URL ?? process.env.STAGEHAND_BASE_URL;


P2: Use || instead of ?? so the fallback semantics match the warning condition. With ??, an empty STAGEHAND_API_URL="" (common in .env files to "unset" a var) prevents STAGEHAND_BASE_URL from being used as a fallback, and the deprecation warning fires spuriously.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/core/lib/v3/api.ts, line 868: <comment>Use `||` instead of `??` so the fallback semantics match the warning condition. With `??`, an empty `STAGEHAND_API_URL=""` (common in .env files to "unset" a var) prevents `STAGEHAND_BASE_URL` from being used as a fallback, and the deprecation warning fires spuriously.</comment> <file context> @@ -861,11 +862,27 @@ export class StagehandAPIClient { + // Use STAGEHAND_API_URL when set. STAGEHAND_BASE_URL is a legacy alias. // Ensure /v1 suffix is present for consistency + const configuredBaseUrl = + process.env.STAGEHAND_API_URL ?? process.env.STAGEHAND_BASE_URL; + if ( + !process.env.STAGEHAND_API_URL && </file context>

Suggested change

process.env.STAGEHAND_API_URL ?? process.env.STAGEHAND_BASE_URL;

process.env.STAGEHAND_API_URL || process.env.STAGEHAND_BASE_URL;

monadoid force-pushed the stg-1808-stagehand-base-url branch 2 times, most recently from 821d82f to 43fa512 Compare April 24, 2026 19:14

monadoid marked this pull request as ready for review April 27, 2026 16:46

cubic-dev-ai Bot reviewed Apr 27, 2026

View reviewed changes

monadoid marked this pull request as draft April 27, 2026 16:55

[STG-1808] Use STAGEHAND_API_URL for Stagehand API client

c24c090

monadoid force-pushed the stg-1808-stagehand-base-url branch from 43fa512 to c24c090 Compare April 27, 2026 16:55

monadoid changed the title ~~[STG-1808] Use STAGEHAND_BASE_URL for Stagehand API client~~ [STG-1808] Use STAGEHAND_API_URL for Stagehand API client Apr 27, 2026

[STG-1808] Remove docs changeset entry

ab2ab29

monadoid marked this pull request as ready for review April 30, 2026 17:45

cubic-dev-ai Bot reviewed Apr 30, 2026

View reviewed changes

pirate approved these changes May 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[STG-1808] Use STAGEHAND_API_URL for Stagehand API client#2040

[STG-1808] Use STAGEHAND_API_URL for Stagehand API client#2040
monadoid wants to merge 2 commits intomainfrom
stg-1808-stagehand-base-url

monadoid commented Apr 24, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Apr 24, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot Apr 27, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -186,6 +186,7 @@ export class StagehandAPIClient {
		private serverCache: boolean;

	process.env.STAGEHAND_API_URL ?? process.env.STAGEHAND_BASE_URL;
	process.env.STAGEHAND_API_URL \|\| process.env.STAGEHAND_BASE_URL;

Conversation

monadoid commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Uh oh!

changeset-bot Bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

monadoid commented Apr 24, 2026 •

edited

Loading

changeset-bot Bot commented Apr 24, 2026 •

edited

Loading

cubic-dev-ai Bot Apr 27, 2026 •

edited

Loading