---
title: "Moving Puppeteer and Playwright jobs to Kitesurf · Junaid Qadir"
description: "Kitesurf is a one-parameter switch for Browser Run CDP scripts. Drop keep_alive when you add it, and keep video, WebGL and bot-challenge jobs on Chromium."
url: "https://junaidqadir.com/blog/moving-puppeteer-and-playwright-jobs-to-kitesurf"
date: "2026-11-19"
tags: ["tools", "web-development", "javascript"]
---

# 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](https://kitesurf.dev/) 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](https://developers.cloudflare.com/browser-run/kitesurf/), 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](https://developers.cloudflare.com/browser-run/cdp/) (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](https://developers.cloudflare.com/browser-run/cdp/puppeteer/) (last updated 26 September 2026), with the edit Kitesurf needs:

```diff
-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:

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

The [Playwright example](https://developers.cloudflare.com/browser-run/cdp/playwright/) 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](https://developers.cloudflare.com/browser-run/kitesurf/) 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:

```sh
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](https://blog.cloudflare.com/kitesurf/) (6 August 2026) reports medians of five Quick Action runs across 14 URLs, against a warm Chromium pool:

<table><thead><tr><th>Task</th><th>Kitesurf</th><th>Chromium</th></tr></thead><tbody><tr><td>Screenshot, CPU</td><td>380 ms</td><td>1,173 ms</td></tr><tr><td>HTML extraction, CPU</td><td>229 ms</td><td>877 ms</td></tr><tr><td>Screenshot, memory</td><td>57.8 MiB</td><td>271.0 MiB</td></tr><tr><td>HTML extraction, memory</td><td>39.4 MiB</td><td>273.7 MiB</td></tr><tr><td>Screenshot, wall time</td><td>1,148 ms</td><td>637 ms</td></tr><tr><td>HTML extraction, wall time</td><td>820 ms</td><td>472 ms</td></tr></tbody></table>

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](https://developers.cloudflare.com/browser-run/pricing/) (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](https://developers.cloudflare.com/browser-run/kitesurf/) 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](https://github.com/cloudflare/kitesurf) 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](https://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](https://junaidqadir.com/blog/ask-claude-code-to-review-how-you-work/) 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.

[JavaScript](https://junaidqadir.com/blog/tag/javascript/)[Tools](https://junaidqadir.com/blog/tag/tools/)[Web development](https://junaidqadir.com/blog/tag/web-development/)

---

Markdown version of https://junaidqadir.com/blog/moving-puppeteer-and-playwright-jobs-to-kitesurf
Site guide for agents: https://junaidqadir.com/llms.txt
Full index: https://junaidqadir.com/sitemap-index.xml
