browser-harness

browser-harness

Direct browser control via CDP. For task-specific edits, use agent-workspace/agent_helpers.py. For setup, install, or connection problems, read https://github.com/browser-use/browser-harness/blob/main/install.md.

Domain skills are off by default. Set BH_DOMAIN_SKILLS=1 to enable them; see the bottom section.

If `BH_DOMAIN_SKILLS=1` and the task is site-specific, read every file in the matching `$BH_AGENT_WORKSPACE/domain-skills/<site>/` directory before inventing an approach.

Usage

browser-harness <<'PY'
print(page_info())
PY

• •Invoke as browser-harness. Use heredocs for multi-line commands.
• •Helpers are pre-imported. run.py calls ensure_daemon() before exec.
• •First navigation is new_tab(url), not goto_url(url).
• •The normal local flow attaches to the running Chrome/Chromium CDP endpoint. No browser ids or local profile selection.

Local Chrome

If the daemon cannot connect, run diagnostics:

browser-harness --doctor

If Chrome remote debugging is not enabled, the harness opens:

chrome://inspect/#remote-debugging

Ask the user to tick "Allow remote debugging for this browser instance" and click Allow if Chrome shows a permission popup. Then retry the same browser-harness command.

Remote Browsers

Use Browser Use cloud for headless servers, parallel sub-agents, or isolated work. Authenticate once:

browser-harness auth login

Or import a key safely:

browser-harness auth login --api-key-stdin

Pick a short made-up name; r7k2 below is just a placeholder:

browser-harness <<'PY'
start_remote_daemon("r7k2")
PY

BU_NAME=r7k2 browser-harness <<'PY'
new_tab("https://example.com")
print(page_info())
PY

When the task is done and a cloud browser is still running, ask directly: "Should I close this browser now?" If yes, run stop_remote_daemon(name). Remote daemons bill until they stop or time out.

Do not start a remote daemon and then keep using the default daemon. Use the same name for BU_NAME.

Cloud profile cookie sync reference: https://github.com/browser-use/browser-harness/blob/main/interaction-skills/profile-sync.md.

Page Workflow

• •Screenshots first: use capture_screenshot() to understand visible state.
• •Clicking: screenshot -> read pixel -> click_at_xy(x, y) -> screenshot again.
• •After navigation, call wait_for_load().
• •If the current tab is stale or internal, call ensure_real_tab().
• •Use js(...) for DOM inspection or extraction when coordinates are the wrong tool.
• •Login walls: stop and ask. Exception: use available SSO automatically when Chrome is already signed in; still stop for passwords, MFA, consent, or ambiguous account choice.
• •Raw CDP is available with cdp("Domain.method", ...).

Interaction Skills

If you get stuck on a browser mechanic, check https://github.com/browser-use/browser-harness/tree/main/interaction-skills.

• •connection.md
• •cookies.md
• •cross-origin-iframes.md
• •dialogs.md
• •downloads.md
• •drag-and-drop.md
• •dropdowns.md
• •iframes.md
• •network-requests.md
• •print-as-pdf.md
• •profile-sync.md
• •screenshots.md
• •scrolling.md
• •shadow-dom.md
• •tabs.md
• •uploads.md
• •viewport.md

Design Constraints

• •Coordinate clicks default. CDP mouse events pass through iframes/shadow/cross-origin at the compositor level.
• •Keep the connection model simple: use the default daemon, BU_NAME, BU_CDP_URL, BU_CDP_WS, or start_remote_daemon(...).
• •Core helpers stay short. Put task-specific helper additions in $BH_AGENT_WORKSPACE/agent_helpers.py.

Gotchas

• •chrome://inspect/#remote-debugging must be enabled for local Chrome control.
• •Chrome may show an "Allow remote debugging?" popup; wait for the user to click Allow.
• •Omnibox popups are not real work tabs.
• •CDP target order is not Chrome's visible tab-strip order.
• •BU_CDP_URL is an HTTP DevTools endpoint; the daemon resolves it to WebSocket.
• •Ask before leaving cloud browsers running; stop them with stop_remote_daemon(name) or PATCH /browsers/{id} {"action":"stop"}.

Domain Skills

Only applies when BH_DOMAIN_SKILLS=1. Otherwise ignore domain skills.

When enabled, search $BH_AGENT_WORKSPACE/domain-skills/<host>/ before inventing an approach. goto_url(...) returns up to 10 skill filenames for the navigated host.