From 13d02ce7fb9ffac74cf3ad13ecc551d63895f7ca Mon Sep 17 00:00:00 2001
From: Chromie <miguel@browserbase.com>
Date: Fri, 23 Jan 2026 17:49:04 -0800
Subject: [PATCH 1/2] docs: add documentation for local browser port option
 (#1586)

# why
Missing docs for local browser port
# what changed
Add documentation for the `port` option in `LocalBrowserLaunchOptions`
that was added in PR #1575. This option allows users to specify a fixed
Chrome CDP debugging port instead of using a randomly assigned port.

Updated:
- packages/docs/v3/references/stagehand.mdx - Added port parameter to
LocalBrowserLaunchOptions documentation
- packages/docs/v3/configuration/browser.mdx - Added port to example and
new "Fixed CDP Debugging Port" section explaining the feature
# test plan

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Document the port option in LocalBrowserLaunchOptions so users can set a
fixed Chrome DevTools Protocol debugging port. Adds examples and
guidance (including a 9222 tip) in the configuration and API reference
pages.

<sup>Written for commit 69f5d613e2c647c0ebaa4639f6eca113c4c17a6e.
Summary will update on new commits.</sup>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Chromie Bot <chromie@browserbase.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
---
 packages/docs/v3/configuration/browser.mdx | 22 ++++++++++++++++++++++
 packages/docs/v3/references/stagehand.mdx  |  6 ++++++
 2 files changed, 28 insertions(+)

diff --git a/packages/docs/v3/configuration/browser.mdx b/packages/docs/v3/configuration/browser.mdx
index f3c3916d2..188bdfbc2 100644
--- a/packages/docs/v3/configuration/browser.mdx
+++ b/packages/docs/v3/configuration/browser.mdx
@@ -186,6 +186,7 @@ const stagehand = new Stagehand({
     devtools: true, // Open developer tools
     viewport: { width: 1280, height: 720 },
     executablePath: '/opt/google/chrome/chrome', // Custom Chrome path
+    port: 9222, // Fixed CDP debugging port
     args: [
       '--no-sandbox',
       '--disable-setuid-sandbox',
@@ -214,6 +215,27 @@ await stagehand.init();
 
 ## Advanced Configuration
 
+### Fixed CDP Debugging Port
+
+Specify a fixed Chrome DevTools Protocol (CDP) debugging port instead of using a randomly assigned one.
+
+```typescript
+import { Stagehand } from "@browserbasehq/stagehand";
+
+const stagehand = new Stagehand({
+  env: "LOCAL",
+  localBrowserLaunchOptions: {
+    port: 9222,
+  },
+});
+
+await stagehand.init();
+```
+
+<Tip>
+Port `9222` is the standard CDP default. Ensure the port is available before launching.
+</Tip>
+
 ### DOM Settle Timeout
 
 Configure how long Stagehand waits for the DOM to stabilize before taking actions.
diff --git a/packages/docs/v3/references/stagehand.mdx b/packages/docs/v3/references/stagehand.mdx
index 692690155..c3481aae5 100644
--- a/packages/docs/v3/references/stagehand.mdx
+++ b/packages/docs/v3/references/stagehand.mdx
@@ -115,6 +115,12 @@ interface V3Options {
       Path to Chrome/Chromium executable.
     </ParamField>
 
+    <ParamField path="port" type="number" optional>
+      Fixed Chrome DevTools Protocol (CDP) debugging port for external tool connections.
+
+      **Default:** Randomly assigned
+    </ParamField>
+
     <ParamField path="args" type="string[]" optional>
       Additional Chrome launch arguments.
     </ParamField>

From 17104a6b390aa4e74fdbac825991fb361c4a21c3 Mon Sep 17 00:00:00 2001
From: Sean McGuire <seanmcguire1@outlook.com>
Date: Fri, 23 Jan 2026 17:55:14 -0800
Subject: [PATCH 2/2] update port tip in config docs

---
 packages/docs/v3/configuration/browser.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docs/v3/configuration/browser.mdx b/packages/docs/v3/configuration/browser.mdx
index 188bdfbc2..2b43227aa 100644
--- a/packages/docs/v3/configuration/browser.mdx
+++ b/packages/docs/v3/configuration/browser.mdx
@@ -233,7 +233,7 @@ await stagehand.init();
 ```
 
 <Tip>
-Port `9222` is the standard CDP default. Ensure the port is available before launching.
+If no `port` is specified, a random port will be assigned.
 </Tip>
 
 ### DOM Settle Timeout