Clarify local Chrome remote debugging setup (#5906)

docker-compose.yml

@@ -64,9 +64,11 @@ services:
       - BROWSER_CDP_CONNECT_TIMEOUT_MS=${BROWSER_CDP_CONNECT_TIMEOUT_MS:-120000}
       - ENABLE_CODE_BLOCK=true
       # --- Control your own browser (Chrome/Chromium) ---
-      # Start Chrome with --remote-debugging-address=0.0.0.0 so Docker can reach it.
+      # Prefer Chrome's chrome://inspect/#remote-debugging flow for an existing profile.
       # On Windows, scripts/windows_chrome_inspect_cdp.ps1 can bridge a
       # chrome://inspect/#remote-debugging listener and write the full ws:// URL.
+      # If Docker cannot reach that listener, start an isolated Chrome profile
+      # with --remote-debugging-address=0.0.0.0 and a non-default --user-data-dir.
       # Then set:
       # - BROWSER_TYPE=cdp-connect
       # - BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/

docs/developers/self-hosted/browser.mdx

@@ -143,8 +143,22 @@ CDP (Chrome DevTools Protocol) lets Skyvern control an external Chrome browser i
 
 ### Step 1: Enable Chrome remote debugging
 
-When Skyvern runs in Docker, Chrome must listen on an address the container can
-reach. Start Chrome manually with `--remote-debugging-address=0.0.0.0`:
+For an already-running Chrome profile, prefer Chrome's built-in remote debugging
+toggle:
+
+1. Open `chrome://inspect/#remote-debugging` in Chrome.
+2. Enable remote debugging for this browser instance.
+3. Keep Chrome open while Skyvern connects.
+
+This path keeps you on your existing Chrome profile. Skyvern will first try to
+auto-discover a local debugging server, then let you paste a direct
+`ws://.../devtools/browser/...` URL if Chrome exposes only a WebSocket endpoint.
+
+#### Docker-reachable isolated profile fallback
+
+When Skyvern runs in Docker, Chrome's built-in listener may bind to host
+loopback only. If the container cannot reach it, start a separate Chrome profile
+with a Docker-reachable CDP endpoint:
 
 <CodeGroup>
 ```bash macOS
@@ -175,7 +189,10 @@ google-chrome \
 ```
 </CodeGroup>
 
-The `--user-data-dir` flag creates a separate profile for Skyvern, preserving your main Chrome profile.
+The `--user-data-dir` flag creates a separate profile for Skyvern, preserving
+your main Chrome profile. Since [Chrome 136](https://developer.chrome.com/blog/remote-debugging-port),
+`--remote-debugging-port` is ignored for the default Chrome data directory, so
+only use these flags with a non-standard user data directory.
 
 #### Windows Docker Desktop with `chrome://inspect`
 
@@ -217,6 +234,11 @@ BROWSER_REMOTE_DEBUGGING_URL=http://host.docker.internal:9222/
 BROWSER_CDP_CONNECT_TIMEOUT_MS=120000
 ```
 
+Use the URL that matches the remote debugging path you chose. For a classic
+HTTP CDP endpoint, use the host and port. For a `chrome://inspect` flow that
+only exposes a browser WebSocket, use the full direct
+`ws://.../devtools/browser/<id>` URL.
+
 When running Skyvern in Docker:
 
 | Host OS | URL |

skyvern/cli/browser.py

@@ -148,7 +148,11 @@ def _print_classic_cdp_instructions() -> None:
     console.print(
         Panel(
             "[bold]Enable Chrome remote debugging[/bold]\n\n"
-            "Start Chrome manually with a CDP endpoint that Docker can reach:\n\n"
+            "Recommended for your existing Chrome profile:\n"
+            "1. Open [cyan]chrome://inspect/#remote-debugging[/cyan] in Chrome.\n"
+            "2. Enable remote debugging for this browser instance.\n\n"
+            "If Skyvern runs in Docker and cannot reach that listener, start an isolated "
+            "Chrome profile with a Docker-reachable CDP endpoint instead:\n\n"
             f"[cyan]{_classic_cdp_launch_command()}[/cyan]",
             border_style="cyan",
         )
@@ -248,7 +252,9 @@ def _setup_local_browser_actual() -> tuple[str, Optional[str], Optional[str]]:
     # Step 2: Guide the user to enable Chrome remote debugging.
     _print_classic_cdp_instructions()
 
-    console.print("\n[bold yellow]Enable remote debugging in Chrome, then press Enter to continue...[/bold yellow]")
+    console.print(
+        "\n[bold yellow]Enable or start remote debugging in Chrome, then press Enter to continue...[/bold yellow]"
+    )
     Prompt.ask("Press Enter when ready", default="")
 
     # Step 3: Auto-discover the debugging server with retries

skyvern/cli/quickstart.py

@@ -262,7 +262,10 @@ def run_docker_compose_setup() -> None:
         from skyvern.cli.browser import _print_classic_cdp_instructions  # noqa: PLC0415
 
         _print_classic_cdp_instructions()
-        confirmed = Confirm.ask("Have you enabled remote debugging in Chrome?", default=False)
+        confirmed = Confirm.ask(
+            "Have you enabled remote debugging in Chrome or started the isolated CDP profile?",
+            default=False,
+        )
         if confirmed:
             from skyvern.cli.llm_setup import update_or_add_env_var
 
@@ -273,8 +276,9 @@ def run_docker_compose_setup() -> None:
         else:
             console.print(
                 "[yellow]No problem - you can configure it later by setting "
-                "BROWSER_TYPE=cdp-connect and starting Chrome with a Docker-reachable "
-                "remote debugging address.[/yellow]"
+                "BROWSER_TYPE=cdp-connect and enabling Chrome remote debugging from "
+                "chrome://inspect/#remote-debugging. If Docker cannot reach that listener, "
+                "start an isolated Chrome profile with a Docker-reachable debugging address.[/yellow]"
             )