Browser CDP Reference

By default, browser_use launches and manages the local Chrome/Chromium via managed CDP, but this does not mean the CDP port should be exposed to the user or other tools every time.

This skill focuses on more "explicit" CDP usage:

1. Scanning local CDP ports
2. Connecting to an existing Chrome (connect_cdp)
3. Explicitly specifying a cdp_port when launching the browser
4. Sharing a single browser instance across multiple agents/tools

In other words:

• The default start uses managed CDP under the hood, but users typically do not need to understand or be aware of CDP details
• Only enter the scope of this skill when the user explicitly mentions "connect to an existing browser / scan ports / specify a port / share a browser"

Privacy Recommendation

If the user does not want to expose browser history, cookies, page content, or session data, recommend using private_mode=true, which switches to Playwright-managed mode.

Warning: One browser instance per workspace

Only one browser can be running or connected per workspace at a time. If a browser instance already exists, you must execute stop first before switching to a new browser or a new CDP connection.

---

When to Use

Use this skill only when the user explicitly expresses one of the following intentions:

• "Connect to my already-open Chrome"
• "Scan for available CDP ports on this machine"
• "Launch the browser with a fixed debug port"
• "Let other agents/tools connect to this browser too"
• "Attach to the browser via the remote debugging port"

In the following cases, you should typically not use this skill:

• The user just says "open the browser"
• The user just says "open a visible window"
• The user does not mention sharing, ports, CDP, or remote debugging

In these cases, use the standard start, adding headed=true if needed — refer to browser_visible.

---

Scenario 1: Scanning Local CDP Ports

Default scan range is 9000–10000:

{"action": "list_cdp_targets"}

Specify a single port:

{"action": "list_cdp_targets", "port": 9222}

Custom scan range:

{"action": "list_cdp_targets", "port_min": 8000, "port_max": 12000}

Use cases:

• The user has manually launched Chrome with a remote debugging port
• You do not know the exact port and need to scan first
• You need to verify available attach targets on the local machine before connecting

---

Scenario 2: Connecting to an Existing Chrome

Connect to an existing CDP endpoint:

{"action": "connect_cdp", "cdp_url": "http://localhost:9222"}

Characteristics:

• After a successful connection, you can continue using standard operations such as open, snapshot, click, type, etc.
• This attaches to an external browser, not a new process launched by QwenPaw
• stop only disconnects — it will not close the external browser
• External CDP connections are also subject to idle auto-stop management, but the auto-stop semantics for external CDP is "auto-disconnect, not close the external browser"

Use cases:

• The user has their own Chrome open and wants the agent to take over directly
• You need to attach to the user's existing login state or open tabs

---

Scenario 3: Launching with an Explicit cdp_port

If the user explicitly requests a fixed port, or needs to provide the endpoint to other tools, specify cdp_port in start:

{"action": "start", "cdp_port": 9222}

To also open a visible window:

{"action": "start", "headed": true, "cdp_port": 9222}

Current behavior:

• If the explicitly specified cdp_port is already in use, an error is raised immediately — it will not forcefully reuse the port
• If cdp_port is not specified, an available port is automatically selected, which usually avoids multi-workspace conflicts
• Auto-selecting an available port still has a tiny race window: between "finding an available port" and "Chrome actually binding to the port", another process could theoretically claim it; on failure, cleanup occurs and an error is reported, but there is no automatic retry

Therefore:

• Do not pass cdp_port proactively when the user has not explicitly requested a port
• Only pass cdp_port explicitly when the user requests a fixed port or external sharing

---

Multi-Workspace and Port Conflicts

The current port strategy for multiple workspaces:

• Explicitly specified port: checks whether 127.0.0.1:cdp_port is already in use; if so, fails immediately and prompts the user to choose a different port or stop the old process
• No explicit port: reduces conflict probability by automatically selecting an available port

This means:

• Multiple workspaces using the default launch can usually coexist
• If multiple workspaces all request the same fixed cdp_port, the later one will fail because the port is already in use

---

Stop Behavior

CDP-related stop behavior differs depending on the type:

1. Managed CDP launched by QwenPaw

For example:

{"action": "start"}

Or:

{"action": "start", "cdp_port": 9222}

These browsers are launched and owned by QwenPaw. stop will:

• Disconnect the Playwright / CDP connection
• Terminate the browser process

2. External CDP Browser

For example:

{"action": "connect_cdp", "cdp_url": "http://localhost:9222"}

These browsers are not launched by QwenPaw. stop will only:

• Disconnect
• Not close the external browser process

---

Division of Responsibility with browser_visible

• browser_visible: handles "whether to show a window" and "whether to use private_mode"
• browser_cdp: handles "whether to connect / expose / specify / scan CDP ports"

In short:

• User cares about "seeing the browser window" → think browser_visible first
• User cares about "connecting to an existing browser / specifying a debug port / sharing with others" → think browser_cdp first

---

Notes

• Although the default start uses managed CDP internally, this is the tool's default implementation detail and does not mean CDP concepts should be exposed to the user every time
• Before using explicit CDP capabilities, warn the user about the risk of sensitive data exposure
• Auto-stop for external CDP means "auto-disconnect," not "auto-close the user's browser"
• Activity is currently refreshed primarily by tool operations; the user's manual interactions in the browser window typically do not reset the idle timer
• private_mode is an explicit parameter for each start call and is not persisted as workspace state