Clarify env var handling in Python SDK

Author: pirate

examples/local_example.py

@@ -5,7 +5,7 @@
 Required environment variables:
 - BROWSERBASE_API_KEY (can be any value in local mode)
 - BROWSERBASE_PROJECT_ID (can be any value in local mode)
-- MODEL_API_KEY (used for client configuration even in local mode)
+- MODEL_API_KEY (read by this example and passed explicitly to the client)
 
 
 Install the published wheel before running this script:
@@ -45,6 +45,7 @@ def _stream_to_result(stream, label: str) -> object | None:
 
 def main() -> None:
     load_example_env()
+    # The example reads MODEL_API_KEY itself so the SDK configuration stays explicit.
     model_key = os.environ.get("MODEL_API_KEY")
     if not model_key:
         sys.exit("Set MODEL_API_KEY to run the local server.")

src/stagehand/_client.py

@@ -92,6 +92,10 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `browserbase_api_key` from `BROWSERBASE_API_KEY`
         - `browserbase_project_id` from `BROWSERBASE_PROJECT_ID`
+
+        `model_api_key` is intentionally not inferred from any AI provider environment variable.
+        Pass it explicitly when you want the SDK to send `x-model-api-key` on remote requests or
+        to forward `MODEL_API_KEY` to the local SEA child process.
         """
         self._server_mode: Literal["remote", "local"] = server
         self._local_stagehand_binary_path = _local_stagehand_binary_path
@@ -366,6 +370,10 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `browserbase_api_key` from `BROWSERBASE_API_KEY`
         - `browserbase_project_id` from `BROWSERBASE_PROJECT_ID`
+
+        `model_api_key` is intentionally not inferred from any AI provider environment variable.
+        Pass it explicitly when you want the SDK to send `x-model-api-key` on remote requests or
+        to forward `MODEL_API_KEY` to the local SEA child process.
         """
         self._server_mode: Literal["remote", "local"] = server
         self._local_stagehand_binary_path = _local_stagehand_binary_path

src/stagehand/lib/sea_server.py

@@ -127,6 +127,9 @@ def _build_process_env(self, *, port: int) -> dict[str, str]:
         proc_env["HOST"] = self._config.host
         proc_env["PORT"] = str(port)
         proc_env["HEADLESS"] = "true" if self._config.headless else "false"
+        # Always set MODEL_API_KEY in the child env so the SDK constructor value wins
+        # over any inherited parent MODEL_API_KEY. An empty string preserves the
+        # "explicitly unset" case instead of silently reusing the parent's value.
         proc_env["MODEL_API_KEY"] = self._config.model_api_key or ""
         if self._config.chrome_path:
             proc_env["CHROME_PATH"] = self._config.chrome_path

tests/test_local_server.py

@@ -263,6 +263,8 @@ def test_local_mode_masks_inherited_model_api_key_envs_and_prefers_explicit_para
     expected_model_api_key: str,
 ) -> None:
     _set_browserbase_env(monkeypatch)
+    # Simulate a parent process with conflicting inherited env. The child SEA process
+    # should keep unrelated env intact while MODEL_API_KEY follows constructor intent.
     monkeypatch.setenv("MODEL_API_KEY", "bad1")
     monkeypatch.setenv("OPENAI_API_KEY", "bad2")