Browser Use

Browser Use with CDP

Drive the browser through its native Chrome DevTools Protocol over the remote-debugging WebSocket. This works with zero dependencies: launch the browser with --remote-debugging-port, then talk JSON over fetch and the built-in WebSocket global (available in Bun and Node ≥ 22 — no ws package).

If the project already has Playwright or Puppeteer installed, using it is usually simpler — reach for raw CDP when no automation library is available, when protocol-level control is needed, or when recording a deterministic visual demo.

Protocol reference: https://chromedevtools.github.io/devtools-protocol/. The running browser's exact schema is at http://127.0.0.1:<port>/json/protocol; tip-of-tree docs can differ from the installed version.

Visible by default when a display exists

When the computer has a display, prefer a visible (headful) browser for any task the user might watch or take over: clicking or typing, forms, sign-in, checkout/payment, CAPTCHAs or bot protection, and user handoff. Most browser tasks exist because plain HTTP is not enough; a headless browser is more likely to trigger bot protection and gives the user no way to observe or step in. Visible does not mean pixel-driven: keep operating the page over CDP, and the user sees every action in the window.

Use headless mode only for work the user explicitly wants in the background and that cannot require interaction or handoff, such as read-only scraping, CI, or screenshot/PDF generation, or when no display exists. A headless page does not satisfy a request to open or reopen a site in a browser the user can see.

When the user asks to review, watch, or take over, leave that browser window open after the task. Do not kill or close it before replying.

Workflow

1. Find a Chromium-based browser (below). If none exists, see "No Chrome installed".
2. Launch with a dedicated profile and remote debugging. Never attach to the user's normal profile unless explicitly asked.
3. Discover targets via /json/list; pick the "page" target by URL or title.
4. Connect to its webSocketDebuggerUrl and enable only the domains you need (usually Page, Runtime, DOM, Input; add Network, Log when debugging).
5. Inspect before acting: find elements by accessible name, label, text, role, stable ID, or placeholder — not generated classes or child indexes.
6. Act through Input.* for user-like interactions; use Runtime.evaluate for inspection, coordinate math, and setup with no meaningful user interaction.
7. Wait on observable state, never fixed sleeps alone.
8. Verify the result (DOM state, URL, screenshot, console/network events).
9. Clean up temporary background work: stop screencasts and close the WebSocket. Kill a browser you launched only when the user did not ask to review, watch, or take over the visible window.

Finding the browser

Any Chromium-based browser supports CDP (Chrome, Chromium, Edge, Brave). Probe in order:

# macOS
for c in "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
         "/Applications/Chromium.app/Contents/MacOS/Chromium" \
         "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" \
         "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"; do
  [ -x "$c" ] && { echo "$c"; break; }
done

# Linux
for c in google-chrome google-chrome-stable chromium chromium-browser microsoft-edge brave-browser; do
  command -v "$c" && break
done

On Windows, check %ProgramFiles%\Google\Chrome\Application\chrome.exe, %ProgramFiles(x86)%\..., %LocalAppData%\Google\Chrome\Application\chrome.exe, and the same patterns for Microsoft\Edge.

No Chrome installed

Any browser found by the probe above works identically — use it. If truly no Chromium-based browser exists, do not install or download one automatically. Tell the user that browser use requires Chrome or another Chromium-based browser and recommend either:

1. Install Chrome on the current computer, then retry the browser task.
2. Teleport the conversation back to its Cloud sandbox, where a browser is already installed.

Wait for the user to choose. Do not silently replace the browser task with plain HTTP or claim browser automation succeeded.

Launching

Use a disposable profile and a fixed port. Chrome refuses to run as root without --no-sandbox, so add that flag when id -u is 0:

chrome_args=( \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/cdp-profile \
  --window-size=1440,900 \
  --force-device-scale-factor=1 \
  --no-first-run \
  --no-default-browser-check \
)
[ "$(id -u)" -eq 0 ] && chrome_args+=(--no-sandbox)
"$CHROME" "${chrome_args[@]}" https://example.com

Add --headless=new only for explicitly invisible work or when no display exists (see "Visible by default" above). With --remote-debugging-port=0, read the chosen port from <user-data-dir>/DevToolsActivePort. Launch in the background and poll http://127.0.0.1:9222/json/version until it responds.

HTTP endpoints: /json/version (browser metadata + browser-level WebSocket URL), /json/list (targets), PUT /json/new?<url> (open tab), /json/activate/<id>, /json/close/<id>, /json/protocol (schema).

Attach to the page target for Page/DOM/Runtime/Input work; use the browser target only for browser-wide commands (target control, downloads, browser contexts).