Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

feat(cli): add --cdp-url flag to connect to existing browser via CDP

Marcin1791462de181
diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.py
index b3dc5758f..9141263f7 100755
--- a/browser_use/skill_cli/main.py
+++ b/browser_use/skill_cli/main.py
@@ -68,7 +68,7 @@ def connect_to_server(session: str, timeout: float = 60.0) -> socket.socket:
return sock
-def ensure_server(session: str, browser: str, headed: bool, profile: str | None, api_key: str | None) -> bool:
+def ensure_server(session: str, browser: str, headed: bool, profile: str | None, api_key: str | None, cdp_url: str | None = None) -> bool:
"""Start server if not running. Returns True if started."""
# Check if server is already running and responsive
if is_server_running(session):
@@ -93,6 +93,8 @@ def ensure_server(session: str, browser: str, headed: bool, profile: str | None,
cmd.append('--headed')
if profile:
cmd.extend(['--profile', profile])
+ if cdp_url:
+ cmd.extend(['--cdp-url', cdp_url])
# Set up environment
env = os.environ.copy()
@@ -194,6 +196,7 @@ Examples:
parser.add_argument('--profile', help='Chrome profile (real browser mode)')
parser.add_argument('--json', action='store_true', help='Output as JSON')
parser.add_argument('--api-key', help='Browser-Use API key')
+ parser.add_argument('--cdp-url', help='CDP URL to connect to existing browser (e.g., http://localhost:9222)')
subparsers = parser.add_subparsers(dest='command', help='Command to execute')
@@ -405,11 +408,11 @@ def main() -> int:
return 1
# Ensure server is running
- ensure_server(args.session, args.browser, args.headed, args.profile, args.api_key)
+ ensure_server(args.session, args.browser, args.headed, args.profile, args.api_key, getattr(args, 'cdp_url', None))
# Build params from args
params = {}
- skip_keys = {'command', 'session', 'browser', 'headed', 'profile', 'json', 'api_key', 'server_command'}
+ skip_keys = {'command', 'session', 'browser', 'headed', 'profile', 'json', 'api_key', 'server_command', 'cdp_url'}
for key, value in vars(args).items():
if key not in skip_keys and value is not None:
diff --git a/browser_use/skill_cli/server.py b/browser_use/skill_cli/server.py
index 4ae594f7d..f0e4e80de 100644
--- a/browser_use/skill_cli/server.py
+++ b/browser_use/skill_cli/server.py
@@ -32,11 +32,13 @@ class SessionServer:
browser_mode: str,
headed: bool,
profile: str | None,
+ cdp_url: str | None = None,
) -> None:
self.session_name = session_name
self.browser_mode = browser_mode
self.headed = headed
self.profile = profile
+ self.cdp_url = cdp_url
self.running = True
self._server: asyncio.Server | None = None
self._shutdown_event: asyncio.Event | None = None
@@ -123,6 +125,7 @@ class SessionServer:
self.browser_mode,
self.headed,
self.profile,
+ self.cdp_url,
)
# Dispatch to handler
@@ -238,6 +241,7 @@ def main() -> None:
parser.add_argument('--browser', default='chromium', choices=['chromium', 'real', 'remote'])
parser.add_argument('--headed', action='store_true', help='Show browser window')
parser.add_argument('--profile', help='Chrome profile (real browser mode)')
+ parser.add_argument('--cdp-url', help='CDP URL to connect to existing browser')
args = parser.parse_args()
logger.info(f'Starting server for session: {args.session}')
@@ -248,6 +252,7 @@ def main() -> None:
browser_mode=args.browser,
headed=args.headed,
profile=args.profile,
+ cdp_url=getattr(args, 'cdp_url', None),
)
try:
diff --git a/browser_use/skill_cli/sessions.py b/browser_use/skill_cli/sessions.py
index 0371e77bd..d98f3868c 100644
--- a/browser_use/skill_cli/sessions.py
+++ b/browser_use/skill_cli/sessions.py
@@ -18,6 +18,7 @@ class SessionInfo:
browser_mode: str
headed: bool
profile: str | None
+ cdp_url: str | None
browser_session: BrowserSession
python_session: PythonSession = field(default_factory=PythonSession)
@@ -38,14 +39,15 @@ class SessionRegistry:
browser_mode: str,
headed: bool,
profile: str | None,
+ cdp_url: str | None = None,
) -> SessionInfo:
"""Get existing session or create new one."""
if name in self._sessions:
return self._sessions[name]
- logger.info(f'Creating new session: {name} (mode={browser_mode}, headed={headed})')
+ logger.info(f'Creating new session: {name} (mode={browser_mode}, headed={headed}, cdp_url={cdp_url})')
- browser_session = await create_browser_session(browser_mode, headed, profile)
+ browser_session = await create_browser_session(browser_mode, headed, profile, cdp_url)
await browser_session.start()
session_info = SessionInfo(
@@ -53,6 +55,7 @@ class SessionRegistry:
browser_mode=browser_mode,
headed=headed,
profile=profile,
+ cdp_url=cdp_url,
browser_session=browser_session,
)
self._sessions[name] = session_info
@@ -97,6 +100,7 @@ async def create_browser_session(
mode: str,
headed: bool,
profile: str | None,
+ cdp_url: str | None = None,
) -> BrowserSession:
"""Create BrowserSession based on mode.
@@ -104,7 +108,12 @@ async def create_browser_session(
- chromium: Playwright-managed Chromium (default)
- real: User's Chrome with profile
- remote: Browser-Use Cloud (requires API key)
+ - cdp_url: Connect to existing browser via CDP URL (takes precedence)
"""
+ # CDP URL takes precedence over other modes
+ if cdp_url:
+ return BrowserSession(cdp_url=cdp_url)
+
if mode == 'chromium':
return BrowserSession(
headless=not headed,