← Blog

BLOG

Click Browser: What It Means and How Agents Drive One

A click browser is a real Chromium instance an agent can click through. Learn how clicks work over CDP, where they fail, and how to run one remotely.

9 min readRemote Browser
Ivory computer towers connected across terracotta platforms in a quiet desert landscape
The infrastructure behind your browserREMOTE BROWSER / ILLUSTRATION

A "click browser" is not a product category with a spec sheet. It is shorthand for a real browser instance that something other than a human — usually an AI agent or an automation script — can click through. The click itself is the easy part. What makes a click browser useful is everything around it: a live DOM, a rendering engine that runs JavaScript, a session that survives long enough to complete a multi-step task, and a control channel that lets your code issue the click and observe the result.

This guide explains how clicks actually work in a browser you control remotely, where they break, and what to check before you put one in production. If you are still deciding between local and hosted runtimes, the remote browser for AI agents overview is a better starting point.

What "click browser" actually refers to

People search for "click browser" in a few different moods:

  • Agent builders who want their LLM-driven agent to click buttons, links, and form controls on a real page.
  • Automation engineers debugging why a Playwright or Puppeteer click() call does nothing.
  • Evaluators comparing hosted browser runtimes that advertise "click" as a primitive.

In all three cases the underlying object is the same: a Chromium instance exposing the Chrome DevTools Protocol (CDP), where a click is a synthesized input event dispatched into the page's event loop. The browser does not know or care whether a human finger or a dispatchMouseEvent command produced it. That is why a click browser can drive real sites — and also why it can be detected, blocked, or silently ignored when the page expects human timing or trusted input.

The distinction that matters for production is where that Chromium runs. A local click browser shares your machine's CPU, network, and cookies. A hosted click browser runs on a provider's infrastructure, is reachable over a WebSocket CDP endpoint, and can be created and destroyed per task. For a deeper comparison of the two models, see remote web browser.

How a click is executed under the hood

When your code calls page.click(selector), Playwright does roughly this:

  1. Resolves the selector to an element handle.
  2. Scrolls the element into view and waits for it to be stable and enabled.
  3. Computes the element's center point in viewport coordinates.
  4. Sends Input.dispatchMouseEvent with type: mousePressed, then mouseReleased, at those coordinates over CDP.
  5. Waits for any navigation or network activity the click triggered.

The browser then runs its normal hit-testing: it finds the topmost element at those coordinates and dispatches mousedown, mouseup, and click events to it. If an overlay, cookie banner, or sticky header sits on top of your target, the click lands on the overlay instead. This is the single most common reason a click "does nothing" — the event fired, but on the wrong element.

Two details matter for agents:

  • Coordinates are viewport-relative. If the page scrolls between the moment you compute the point and the moment the event dispatches, you click the wrong thing. Playwright's actionability checks reduce this window but do not eliminate it on animated pages.
  • Trusted vs. untrusted events. CDP-dispatched input is treated as trusted by the browser (unlike element.click() from page JavaScript), which is why it triggers default behaviors like form submission and navigation. Some anti-bot systems still distinguish it via timing and pointer-movement heuristics.

Driving a click browser over CDP

The practical way to run a click browser remotely is to connect Playwright to a hosted Chromium session over CDP. The provider gives you a WebSocket endpoint; you pass it to chromium.connectOverCDP() and then use the normal Playwright API, including click().

import { chromium } from "playwright";

const CDP_ENDPOINT = process.env.BROWSER_CDP_URL!; // wss://... from your session

async function clickThrough() {
  const browser = await chromium.connectOverCDP(CDP_ENDPOINT);
  const context = browser.contexts()[0] ?? (await browser.newContext());
  const page = context.pages()[0] ?? (await context.newPage());

  await page.goto("https://example.com/login", { waitUntil: "domcontentloaded" });

  // Prefer role/label locators over CSS — they survive markup churn.
  await page.getByLabel("Email").fill("agent@example.com");
  await page.getByLabel("Password").fill(process.env.SITE_PASSWORD!);

  // Wait for the click to actually cause navigation, not just fire.
  await Promise.all([
    page.waitForURL("**/dashboard", { timeout: 15_000 }),
    page.getByRole("button", { name: "Sign in" }).click(),
  ]);

  const heading = await page.getByRole("heading", { level: 1 }).innerText();
  console.log("Landed on:", heading);

  await browser.close(); // ends the remote session
}

clickThrough().catch((err) => {
  console.error("click browser failed:", err);
  process.exit(1);
});

A few things in that snippet are deliberate:

  • `connectOverCDP` instead of `launch`. You are not starting a browser; you are attaching to one that already exists. The provider owns the process lifecycle.
  • `Promise.all` around the click and the navigation wait. A click that triggers navigation will otherwise race your waitForURL. Wrapping both means the wait is armed before the click fires.
  • Role-based locators. getByRole("button", { name: "Sign in" }) resolves to the accessible name, which is far more stable than a generated class name when the site ships a new build.

The Playwright documentation on `connectOverCDP` is the authoritative reference for connection options, and the Chrome DevTools Protocol Input domain documents the underlying dispatchMouseEvent command if you need to drop below Playwright.

Where clicks fail in production

A click browser that works in a demo often fails at scale. The failure modes cluster into a few categories.

Element not actionable

The element exists in the DOM but is covered, disabled, off-screen, or animating. Playwright's auto-waiting handles most of this, but it will time out rather than guess. Fixes: dismiss overlays explicitly, wait for networkidle or a specific selector, or use force: true only when you have confirmed the overlay is cosmetic.

Click fires but nothing happens

Usually one of: the handler is bound to a different element (event delegation), the click needs a preceding mousedown/mouseup pair with a delay, or the page requires a pointerdown event that Playwright's default click does not emit on some custom widgets. For custom controls, page.mouse.move() then page.mouse.down()/up() with a small delay often works where click() does not.

Session dies mid-task

Long agent tasks — form filling, multi-page checkout, research loops — can outlive a short-lived browser session. If your provider caps session duration or recycles idle browsers, a click late in the task hits a dead connection. Check session limits before you design a workflow; pricing pages usually state duration and concurrency caps.

Detection

Sites that fingerprint input timing, pointer trajectories, or headless markers may accept the click but route the session to a challenge. Hosted runtimes with configurable browser settings and proxy options reduce this, but no runtime guarantees bypass. Treat detection as a risk to measure, not a feature to assume.

State loss between steps

If each click runs in a fresh browser, logins and cart state vanish. Persistent profiles solve this by keeping cookies and storage across sessions. The remote browser online guide covers how session persistence works in practice.

Local vs. hosted click browser: what changes

DimensionLocal click browserHosted click browser
Where Chromium runsYour machine or CI runnerProvider infrastructure
Connectionlaunch()connectOverCDP() over WebSocket
ScalingLimited by local CPU/RAMCreate sessions per task via API
Session lifetimeTied to your processProvider-defined; check limits
State persistenceYour diskPersistent profiles via API
Network identityYour IPConfigurable proxy settings
DebuggingLocal devtoolsLive viewer + CDP
Failure isolationOne crash kills the runSessions isolated per task

The trade-off is control versus operational burden. Local gives you full control and zero per-hour cost, but you own the Chrome version pinning, the memory leaks, the zombie processes, and the IP reputation. Hosted moves that to the provider and gives you an API to create and destroy sessions, at the cost of a metered runtime and a dependency on someone else's uptime.

For agent workloads specifically, the hosted model tends to win because agents are long-running, bursty, and need isolation between tasks. A single agent that clicks through ten sites should not share cookies or a process with the next task.

Criteria for choosing a click browser runtime

Before you commit, evaluate against these:

  • CDP fidelity. Does the runtime expose a standard CDP WebSocket endpoint that Playwright, Puppeteer, and Selenium can all attach to? Proprietary control APIs lock you in.
  • Session lifecycle. Can you create, inspect, and terminate sessions programmatically? Is there a live viewer for debugging a stuck click?
  • Persistence. Do profiles survive across sessions so logins and carts carry over?
  • Network controls. Are proxy and browser settings configurable per session?
  • Isolation. Does each session get its own browser context, or do tasks share state?
  • Observability. Can you see console logs, network requests, and screenshots from a failed click?
  • Usage controls. Are concurrency and duration limits documented, and can you set budgets?

The documentation covers how Remote Browser exposes these primitives — hosted Chromium sessions, CDP access, Playwright/Puppeteer/Selenium compatibility, a live viewer, persistent profiles, and configurable browser settings — so you can map them against the list above.

Making clicks reliable

A few habits separate click browsers that hold up from ones that flake:

  1. Assert the outcome, not the click. After every click, wait for a specific state change — a URL, a visible element, a network response. A click that returns without error proves nothing.
  2. Prefer semantic locators. Roles, labels, and text survive redesigns; CSS paths and XPath do not.
  3. Handle overlays first. Cookie banners and modals are the top cause of misdirected clicks. Dismiss them before interacting with the page.
  4. Set explicit timeouts. Default timeouts are tuned for humans, not agents. Set per-action timeouts that match the site's real latency.
  5. Capture evidence on failure. Screenshot, DOM snapshot, and console log on every failed click so you can debug without reproducing.
  6. Keep sessions short and scoped. One task, one session, one profile. Long-lived shared sessions accumulate state that causes nondeterministic failures.

If you want to watch a click happen in real time — useful when an agent reports success but the page did not change — a live viewer is the fastest debugging tool. The remote control browser guide explains how live session control works.

Bottom line

A click browser is a real Chromium instance driven over CDP, and the click is only as reliable as the session, locator strategy, and failure handling around it. For agent workloads, a hosted runtime removes the infrastructure burden and gives you per-task isolation, persistent profiles, and a live viewer for debugging. Start by connecting Playwright to a remote session with connectOverCDP, assert outcomes after every click, and check pricing for current session limits before you design a long-running workflow.