STG-1808: Deprecate browserbase project ID (#87)

monadoid · samfinton · web-flow · commit 98a399cbdf49 · 2026-05-06T21:55:04.000+02:00
* Deprecate browserbase project ID

* Fix Ruby project ID assertion

---------

Co-authored-by: samfinton &lt;samfinton@samLaptopm5.galaxus.box&gt;
diff --git a/README.md b/README.md
@@ -90,7 +90,6 @@ require "playwright"
 
 client = Stagehand::Client.new(
   browserbase_api_key: ENV["BROWSERBASE_API_KEY"],
-  browserbase_project_id: ENV["BROWSERBASE_PROJECT_ID"],
   model_api_key: ENV["MODEL_API_KEY"],
   server: "remote"
 )
@@ -162,10 +161,10 @@ client.sessions.end_(session_id)
 
 Set your environment variables (from `examples/.env.example`):
 
-- `STAGEHAND_API_URL`
 - `MODEL_API_KEY`
 - `BROWSERBASE_API_KEY`
-- `BROWSERBASE_PROJECT_ID`
+
+`STAGEHAND_API_URL` is optional and defaults to the hosted Stagehand API. `STAGEHAND_BASE_URL` remains supported as a deprecated fallback when `STAGEHAND_API_URL` is unset.
 
 ```bash
 cp examples/.env.example examples/.env
diff --git a/examples/.env.example b/examples/.env.example
@@ -1,4 +1,2 @@
-STAGEHAND_API_URL=https://api.stagehand.browserbase.com
 MODEL_API_KEY=sk-proj-your-llm-api-key-here
 BROWSERBASE_API_KEY=bb_live_your_api_key_here
-BROWSERBASE_PROJECT_ID=your-bb-project-uuid-here
diff --git a/examples/env.rb b/examples/env.rb
@@ -2,10 +2,8 @@
 
 module ExampleEnv
   REQUIRED_KEYS = %w[
-    STAGEHAND_API_URL
     MODEL_API_KEY
     BROWSERBASE_API_KEY
-    BROWSERBASE_PROJECT_ID
   ].freeze
 
   def self.load!
diff --git a/examples/local_browser_playwright_example.rb b/examples/local_browser_playwright_example.rb
@@ -16,12 +16,10 @@
 
 model_key = ENV["MODEL_API_KEY"]
 browserbase_api_key = ENV["BROWSERBASE_API_KEY"].to_s
-browserbase_project_id = ENV["BROWSERBASE_PROJECT_ID"].to_s
 
 missing = []
 missing << "MODEL_API_KEY" if model_key.to_s.empty?
 missing << "BROWSERBASE_API_KEY" if browserbase_api_key.empty?
-missing << "BROWSERBASE_PROJECT_ID" if browserbase_project_id.empty?
 
 unless missing.empty?
   warn("Set #{missing.join(', ')} to run the local Playwright example.")
@@ -60,7 +58,6 @@ def stream_with_result(label, stream)
 
 client = Stagehand::Client.new(
   browserbase_api_key: browserbase_api_key,
-  browserbase_project_id: browserbase_project_id,
   model_api_key: model_key,
   server: "local"
 )
diff --git a/examples/local_server_multiregion_browser_example.rb b/examples/local_server_multiregion_browser_example.rb
@@ -7,12 +7,10 @@
 require_relative "env"
 ExampleEnv.load!
 browserbase_api_key = ENV["BROWSERBASE_API_KEY"].to_s
-browserbase_project_id = ENV["BROWSERBASE_PROJECT_ID"].to_s
 model_key = ENV["MODEL_API_KEY"].to_s
 
 missing = []
 missing << "BROWSERBASE_API_KEY" if browserbase_api_key.empty?
-missing << "BROWSERBASE_PROJECT_ID" if browserbase_project_id.empty?
 missing << "MODEL_API_KEY" if model_key.empty?
 
 unless missing.empty?
@@ -22,7 +20,6 @@
 
 client = Stagehand::Client.new(
   browserbase_api_key: browserbase_api_key,
-  browserbase_project_id: browserbase_project_id,
   model_api_key: model_key,
   server: "local"
 )
diff --git a/examples/remote_browser_example.rb b/examples/remote_browser_example.rb
@@ -7,12 +7,10 @@
 require_relative "env"
 ExampleEnv.load!
 browserbase_api_key = ENV["BROWSERBASE_API_KEY"].to_s
-browserbase_project_id = ENV["BROWSERBASE_PROJECT_ID"].to_s
 model_key = ENV["MODEL_API_KEY"].to_s
 
 missing = []
 missing << "BROWSERBASE_API_KEY" if browserbase_api_key.empty?
-missing << "BROWSERBASE_PROJECT_ID" if browserbase_project_id.empty?
 missing << "MODEL_API_KEY" if model_key.empty?
 
 unless missing.empty?
@@ -22,7 +20,6 @@
 
 client = Stagehand::Client.new(
   browserbase_api_key: browserbase_api_key,
-  browserbase_project_id: browserbase_project_id,
   model_api_key: model_key
 )
 
diff --git a/examples/remote_browser_playwright_example.rb b/examples/remote_browser_playwright_example.rb
@@ -16,12 +16,10 @@
 
 model_key = ENV["MODEL_API_KEY"]
 browserbase_api_key = ENV["BROWSERBASE_API_KEY"].to_s
-browserbase_project_id = ENV["BROWSERBASE_PROJECT_ID"].to_s
 
 missing = []
 missing << "MODEL_API_KEY" if model_key.to_s.empty?
 missing << "BROWSERBASE_API_KEY" if browserbase_api_key.empty?
-missing << "BROWSERBASE_PROJECT_ID" if browserbase_project_id.empty?
 
 unless missing.empty?
   warn("Set #{missing.join(', ')} to run the remote Playwright example.")
@@ -83,7 +81,6 @@ def stream_with_result(label, stream)
 
 client = Stagehand::Client.new(
   browserbase_api_key: browserbase_api_key,
-  browserbase_project_id: browserbase_project_id,
   model_api_key: model_key,
   server: "remote"
 )
diff --git a/lib/stagehand/client.rb b/lib/stagehand/client.rb
@@ -34,7 +34,7 @@ class Client < Stagehand::Internal::Transport::BaseClient
     #
     # @return [Hash{String=>String}]
     private def auth_headers
-      {**bb_api_key_auth, **bb_project_id_auth, **llm_model_api_key_auth}
+      {**bb_api_key_auth, **llm_model_api_key_auth}
     end
 
     # @api private
@@ -48,7 +48,7 @@ class Client < Stagehand::Internal::Transport::BaseClient
     #
     # @return [Hash{String=>String}]
     private def bb_project_id_auth
-      {"x-bb-project-id" => @browserbase_project_id}
+      {}
     end
 
     # @api private
@@ -63,16 +63,17 @@ class Client < Stagehand::Internal::Transport::BaseClient
     # @param browserbase_api_key [String, nil] Your [Browserbase API Key](https://www.browserbase.com/settings) Defaults to
     # `ENV["BROWSERBASE_API_KEY"]`
     #
-    # @param browserbase_project_id [String, nil] Your [Browserbase Project ID](https://www.browserbase.com/settings) Defaults to
-    # `ENV["BROWSERBASE_PROJECT_ID"]`
+    # @param browserbase_project_id [String, nil] Deprecated. Browserbase API keys are now project-scoped, so
+    # this value is accepted for backwards compatibility and ignored.
     #
     # @param model_api_key [String, nil] Your LLM provider API key (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
     # Defaults to `ENV["MODEL_API_KEY"]`
     #
     # @param server [String] Server mode to use ("remote" or "local"). Defaults to "remote"
     #
     # @param base_url [String, nil] Override the default base URL for the API, e.g.,
-    # `"https://api.example.com/v2/"`. Defaults to `ENV["STAGEHAND_API_URL"]`
+    # `"https://api.example.com/v2/"`. Defaults to `ENV["STAGEHAND_API_URL"]`,
+    # then `ENV["STAGEHAND_BASE_URL"]`
     #
     # @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
     #
@@ -83,7 +84,7 @@ class Client < Stagehand::Internal::Transport::BaseClient
     # @param max_retry_delay [Float]
     def initialize(
       browserbase_api_key: ENV["BROWSERBASE_API_KEY"],
-      browserbase_project_id: ENV["BROWSERBASE_PROJECT_ID"],
+      browserbase_project_id: nil,
       model_api_key: ENV["MODEL_API_KEY"],
       server: "remote",
       base_url: ENV["STAGEHAND_API_URL"] || ENV["STAGEHAND_BASE_URL"],
@@ -99,10 +100,6 @@ def initialize(
         raise ArgumentError,
               "browserbase_api_key is required, and can be set via environ: \"BROWSERBASE_API_KEY\""
       end
-      if browserbase_project_id.nil?
-        raise ArgumentError,
-              "browserbase_project_id is required, and can be set via environ: \"BROWSERBASE_PROJECT_ID\""
-      end
       if model_api_key.nil?
         raise ArgumentError,
               "model_api_key is required, and can be set via environ: \"MODEL_API_KEY\""
diff --git a/lib/stagehand/local.rb b/lib/stagehand/local.rb
@@ -50,7 +50,6 @@ def self.ensure_browserbase_credentials!(client:, params:)
 
       missing = []
       missing << "browserbase_api_key" if client.browserbase_api_key.to_s.empty?
-      missing << "browserbase_project_id" if client.browserbase_project_id.to_s.empty?
       return if missing.empty?
 
       message =
@@ -213,10 +212,9 @@ def ensure_executable(path)
     end
 
     class ServerManager
-      def initialize(model_api_key:, browserbase_api_key:, browserbase_project_id:)
+      def initialize(model_api_key:, browserbase_api_key:)
         @model_api_key = model_api_key
         @browserbase_api_key = browserbase_api_key
-        @browserbase_project_id = browserbase_project_id
         @host = DEFAULT_HOST
         @port = 0
         @mutex = Mutex.new
@@ -335,9 +333,6 @@ def build_env(host:, port:)
         if @browserbase_api_key.to_s != ""
           env["BROWSERBASE_API_KEY"] = @browserbase_api_key
         end
-        if @browserbase_project_id.to_s != ""
-          env["BROWSERBASE_PROJECT_ID"] = @browserbase_project_id
-        end
         env
       end
 
@@ -376,8 +371,6 @@ def initialize(server: "remote", **kwargs)
           kwargs[:base_url] = base_url.nil? ? "http://#{DEFAULT_HOST}" : base_url
           kwargs[:browserbase_api_key] =
             kwargs[:browserbase_api_key] || ENV["BROWSERBASE_API_KEY"] || ""
-          kwargs[:browserbase_project_id] =
-            kwargs[:browserbase_project_id] || ENV["BROWSERBASE_PROJECT_ID"] || ""
         end
 
         super(**kwargs)
@@ -386,8 +379,7 @@ def initialize(server: "remote", **kwargs)
 
         @local_server_manager = Stagehand::Local::ServerManager.new(
           model_api_key: @model_api_key,
-          browserbase_api_key: @browserbase_api_key,
-          browserbase_project_id: @browserbase_project_id
+          browserbase_api_key: @browserbase_api_key
         )
       end
 
@@ -421,8 +413,7 @@ def bb_api_key_auth
       end
 
       def bb_project_id_auth
-        return {} if @browserbase_project_id.to_s.empty?
-        super
+        {}
       end
     end
 
diff --git a/rbi/stagehand/client.rbi b/rbi/stagehand/client.rbi
@@ -14,7 +14,7 @@ module Stagehand
     sig { returns(String) }
     attr_reader :browserbase_api_key
 
-    # Your [Browserbase Project ID](https://www.browserbase.com/settings)
+    # Deprecated. Browserbase API keys are now project-scoped, so this value is accepted for backwards compatibility and ignored.
     sig { returns(String) }
     attr_reader :browserbase_project_id
 
@@ -63,16 +63,16 @@ module Stagehand
       # Your [Browserbase API Key](https://www.browserbase.com/settings) Defaults to
       # `ENV["BROWSERBASE_API_KEY"]`
       browserbase_api_key: ENV["BROWSERBASE_API_KEY"],
-      # Your [Browserbase Project ID](https://www.browserbase.com/settings) Defaults to
-      # `ENV["BROWSERBASE_PROJECT_ID"]`
-      browserbase_project_id: ENV["BROWSERBASE_PROJECT_ID"],
+      # Deprecated. Browserbase API keys are now project-scoped, so this value is accepted for backwards compatibility and ignored.
+      browserbase_project_id: nil,
       # Your LLM provider API key (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
       # Defaults to `ENV["MODEL_API_KEY"]`
       model_api_key: ENV["MODEL_API_KEY"],
       # Server mode to use ("remote" or "local"). Defaults to "remote"
       server: "remote",
       # Override the default base URL for the API, e.g.,
-      # `"https://api.example.com/v2/"`. Defaults to `ENV["STAGEHAND_API_URL"]`
+      # `"https://api.example.com/v2/"`. Defaults to `ENV["STAGEHAND_API_URL"]`,
+      # then `ENV["STAGEHAND_BASE_URL"]`
       base_url: ENV["STAGEHAND_API_URL"] || ENV["STAGEHAND_BASE_URL"],
       # Max number of retries to attempt after a failed retryable request.
       max_retries: Stagehand::Client::DEFAULT_MAX_RETRIES,
diff --git a/test/stagehand/client_test.rb b/test/stagehand/client_test.rb
@@ -76,6 +76,29 @@ def test_client_base_url_prefers_stagehand_api_url
     end
   end
 
+  def test_client_omits_project_id_header
+    captured_headers = nil
+    stub_request(:post, "http://localhost/v1/sessions/start")
+      .with do |request|
+        captured_headers = request.headers
+        true
+      end
+      .to_return_json(status: 200, body: {})
+
+    stagehand =
+      Stagehand::Client.new(
+        base_url: "http://localhost",
+        browserbase_api_key: "My Browserbase API Key",
+        browserbase_project_id: "My Browserbase Project ID",
+        model_api_key: "My Model API Key"
+      )
+
+    stagehand.sessions.start(model_name: "openai/gpt-5.4-mini")
+
+    refute_nil(captured_headers)
+    refute_includes(captured_headers.keys.map(&:downcase), "x-bb-project-id")
+  end
+
   def with_env(vars)
     old_values = vars.keys.to_h { |key| [key, ENV.fetch(key, nil)] }
 
