Moving Puppeteer and Playwright jobs to Kitesurf

A typical Browser Run job connects Puppeteer to Cloudflare’s CDP endpoint, opens one page, takes a screenshot or pulls the HTML, and closes. No login, no video, no state worth keeping. Every one of those runs still gets a full Chromium.

Cloudflare now has a second engine for that kind of job. Kitesurf is a browser engine that runs on Workers in V8 isolates, with no Chromium underneath, and it speaks the Chrome DevTools Protocol. You opt in by adding browser=kitesurf to the Browser Run endpoint you already use (Kitesurf docs, last updated 13 November 2026). It is free while in beta, subject to per-account limits.

The fix for most scripts is one query parameter, with one catch. Cloudflare’s own Puppeteer and Playwright examples connect with ?keep_alive=600000, and the CDP reference (last updated 30 September 2026) says of the browser parameter: “Do not combine it with keep_alive, lab, or recording.” So you replace keep_alive, you do not append to it.

Keep four kinds of job on Chromium: video, WebGL, bot challenges that need a real TLS fingerprint, and long logged-in sessions that need persistent state. Cloudflare lists all four as current limitations.

Nothing in this post was run. Browser Run needs a Cloudflare account and an API token, and neither was available for this test. Everything below comes from Cloudflare’s docs, its announcement post and the Kitesurf repo, all checked on 18 November 2026. The commands are copied from those sources and labelled where they have been edited.

The one-line change

This is the connection line from Cloudflare’s Puppeteer over CDP example (last updated 26 September 2026), with the edit Kitesurf needs:

-const browserWSEndpoint = `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-run/devtools/browser?keep_alive=600000`;
+const browserWSEndpoint = `wss://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/browser-run/devtools/browser?browser=kitesurf`;

The rest of that example stays as it is. It uses puppeteer-core and passes the token as a header:

const browser = await puppeteer.connect({
	browserWSEndpoint,
	headers: {
		Authorization: `Bearer ${API_TOKEN}`,
	},
});

The Playwright example builds the same URL, also with keep_alive=600000, and passes it to chromium.connectOverCDP() with the same header. It needs the same edit. The Kitesurf docs say existing Puppeteer, Playwright and chrome-remote-interface setups work with this change. The token needs the Browser Rendering - Edit permission, according to the CDP reference.

The reference does not say what session lifetime a Kitesurf connection gets once keep_alive is gone. For Chromium, the keep_alive default is 60 seconds. If your script runs longer than a minute, find out before you rely on it.

If you call Quick Actions over REST instead, this is the screenshot request from the Kitesurf docs:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-run/screenshot?browser=kitesurf' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com"
  }' \
  --output "screenshot.png"

From inside a Worker, you pass browser: "kitesurf" to env.BROWSER.quickAction(). The docs add that wrangler dev throws an error for Kitesurf, so local testing needs "remote": true on the binding.

What the numbers say

Cloudflare’s announcement post (6 August 2026) reports medians of five Quick Action runs across 14 URLs, against a warm Chromium pool:

Task Kitesurf Chromium
Screenshot, CPU 380 ms 1,173 ms
HTML extraction, CPU 229 ms 877 ms
Screenshot, memory 57.8 MiB 271.0 MiB
HTML extraction, memory 39.4 MiB 273.7 MiB
Screenshot, wall time 1,148 ms 637 ms
HTML extraction, wall time 820 ms 472 ms

That works out to 3.1 to 3.8 times less CPU and 4.7 to 7.0 times less memory. It is also 1.7 to 1.8 times slower by the clock. The post says so itself: Chromium “wins the stopwatch”.

These are vendor numbers on a vendor-chosen corpus. No independent measurement turned up while researching this post.

The cost case needs reading carefully. Kitesurf is free during the beta. The Browser Run pricing page (last updated 21 April 2026) charges Chromium by the browser hour, $0.09 an hour after the 10 included on Workers Paid, and does not mention Kitesurf at all. The announcement calls CPU and memory “the things that actually drive your bill”, but no post-beta price has been published. If Kitesurf ended up billed by the hour like Chromium, a job that runs 1.8 times longer would not be cheaper. For now it is cheaper because it is free.

What stays on Chromium

The Kitesurf docs list the current limitations as:

  • video playback and WebGL rendering
  • bot-challenge handshakes that require real TLS fingerprints
  • long-running, authenticated sessions that need persistent state

For those, the docs point you back to Browser Run’s default Chromium browser. In practice that rules out a few common jobs: anything that logs in once and reuses the session, maps and 3D canvases, and scraping sites that sit behind a challenge page.

The CDP parameter rules add two more. A job that needs recording=true for debugging, or lab=true for experimental Chrome features, cannot use Kitesurf, because the parameters cannot be combined.

On the other side, the docs say Kitesurf renders TodoMVC (vanilla, React, Vue, Angular and Preact), Wikipedia, Hacker News, the Cloudflare Blog and much of the Cloudflare dashboard. It passes over 235,000 Web Platform Tests subtests. The docs also note that WPT measures standards conformance, not whether a particular site works. A screenshot that comes back without an error can still be wrong.

Running it yourself

The engine source is on GitHub under Apache-2.0. The README (checked 18 November 2026) says local setup needs Bazelisk, Node.js 22 or later and pnpm 9.15.4 (plus GNU tar on macOS), then pnpm install --frozen-lockfile and pnpm run dev, which serves the engine at http://127.0.0.1:8787. The same README warns: “Do not open untrusted sites with a local Kitesurf”, because page JavaScript runs in workerd, which is not a hardened sandbox. Deploying your own copy needs the Workers Paid plan, and the engine has no authentication of its own, so the README says to put Cloudflare Access in front of it.

There is also a public playground at kitesurf.dev that needs no account. It lets you load a URL and inspect the DOM, console and network.

If you drive a browser from a coding agent, the same endpoint works through chrome-devtools-mcp. The Kitesurf docs include an MCP config that passes --wsEndpoint with ?browser=kitesurf and the token in --wsHeaders. The Claude Code self-review prompt asks how you verify work, and screenshots are one of the answers. An agent taking those screenshots is exactly the stateless, one-page job Kitesurf is built for.

Try it on one job

Search your code for devtools/browser?keep_alive. Pick one call site that only screenshots or extracts HTML from a public page, with no login. Copy it, swap keep_alive=600000 for browser=kitesurf, and run both versions against the same ten URLs. Compare the screenshots by eye and diff the HTML. Where they match, move the job. Where they do not, you have found a page Kitesurf cannot render yet, and the Chromium endpoint is still one parameter away.

Comments

← All posts