Playbooks · Coding tasks
Self-host Kitesurf with authentication first
Written November 16, 2026
Cloudflare's Kitesurf browser engine is open source and has no authentication of its own. Put Access in front before the public URL exists.
Cloudflare made Kitesurf open source on November 13, 2026, in its launch post. Kitesurf is an experimental browser engine that runs on Cloudflare Workers. The repository README describes what it does: it parses HTML, applies CSS, runs page JavaScript, and renders screenshots, all without Chrome or a browser container. Because it speaks the Chrome DevTools Protocol, an agent or a script can drive it with a CDP client such as Puppeteer.
That shape is the appeal for agent work: a browsing step can run inside a Worker rather than on a machine you keep running. The catch sits in the README's deployment section, and it is blunt: the engine has no authentication of its own. Set up authentication first, run the engine locally second, and deploy only once the public address is already behind Cloudflare Access.
What you need before you start
- A Workers Paid plan for any Cloudflare run. Kitesurf needs Dynamic Workers to create an isolated worker for each page, and Dynamic Workers are part of the Workers Paid plan. Local development uses
wrangler dev, but running the engine on Cloudflare needs the paid plan. - Bazelisk, installed as
bazel. Bazel builds everything, and it downloads the pinned Bazel, Rust toolchains, wasm-bindgen, and binaryen itself. - Node.js 22 or newer, and pnpm 9.15.4. The repository pins that pnpm version in
package.json. If pnpm is missing, the README givesnpm install --global pnpm@9.15.4. - GNU tar on macOS, from
brew install gnu-tar.
Run it locally first
Clone the repository, install dependencies with the lockfile, and start the engine:
git clone https://github.com/cloudflare/kitesurf.git, thencd kitesurfpnpm install --frozen-lockfilepnpm run dev
The engine listens on http://127.0.0.1:8787. Open http://127.0.0.1:8787/health to confirm it is running, and open the root URL for a landing page with a form to open a URL in DevTools, example pages, and the CDP endpoints. If port 8787 is already in use, set KITESURF_PORT, for example KITESURF_PORT=8799 pnpm run dev, and use that port in the addresses that follow. The first build compiles the Rust core and its vendored crates and takes a while; later builds reuse Bazel's cache.
To drive the local engine from a script, install puppeteer-core in your own project and connect to the browser WebSocket endpoint:
import puppeteer from "puppeteer-core";
const browser = await puppeteer.connect({
browserWSEndpoint: "ws://127.0.0.1:8787/devtools/browser",
});
const page = await browser.newPage();
await page.goto("https://example.com/");
await page.screenshot({ path: "page.png" });
await browser.disconnect();
HTTP discovery is also available at http://127.0.0.1:8787/json/version.
Put authentication in front before you deploy
The README's deployment warning names what a person who has your Worker URL can do with it. They can open DevTools and browse the web through your engine. They can connect Puppeteer and other CDP clients to it. They can send outbound requests that come from your Cloudflare account. And they can use CPU time and Dynamic Workers that your account pays for. None of that needs a password, because the engine has none.
Finding the URL is not much of a barrier either. The workers.dev URL is public by default, and its name follows a predictable pattern: kitesurf.<your-subdomain>.workers.dev. So the deploy order in the README runs in two stages, with a preparation step in front of both:
- Before deploying, turn on Access for all Workers in the account. The README points to this as the way to close the gap between deploying and protecting the URL. Between those two steps, an unprepared engine is public.
- Deploy from the repository root with
pnpm run deploy. The command builds with Bazel and uploads with Wrangler, using the account fromwrangler loginor theCLOUDFLARE_ACCOUNT_IDandCLOUDFLARE_API_TOKENvalues; without--name, the Worker name iskitesurf. - Protect the Worker URL with Cloudflare Access immediately, following the README's link to managing access to
workers.dev. For a custom domain or route, use a self-hosted Access application instead. Then open the Worker URL in Chrome: Access asks you to sign in, and the landing page opens after that.
Two details are easy to miss. Version URLs are public too: pnpm run deploy:preview uploads a version without sending traffic to it, and if Version URLs are turned on, that address also needs Access in front of it. And an automated CDP client cannot sign in the way a person does. For Puppeteer through Access, the README's route is an Access service token plus a policy with the Service Auth action allowing that token. Send the token as CF-Access-Client-Id and CF-Access-Client-Secret headers on the WebSocket connection to wss://<worker-host>/devtools/browser. Keep that token secret; it carries the same access as a signed-in user.
Limits
- Kitesurf provides a CDP endpoint, not a full Chrome implementation. Some Chrome DevTools features do not work yet, and the README says more support is being added over time. Test the exact DevTools or Puppeteer calls your agent depends on before you build on them.
- The hosted DevTools frontend can connect only to
127.0.0.1, so it does not work with a deployed engine; a deployed engine uses the bundled frontend, which the deploy build includes.
Related playbooks
- AIDE2's self-improvement claim vs Epoch's evaluation
- VS Code 1.145: Agent Host keeps sessions alive
- Ouroboros: the agent that rewrites itself
- Add tests to an untested module with an agent
Sources
- cloudflare/kitesurf — GitHub — the repository README: what the engine does, the requirements, the local run and Puppeteer connection, and the deployment warning with the Access steps.
- Kitesurf is now open source — Cloudflare Blog — the November 13, 2026 post announcing that Kitesurf is open source.
- Dynamic Workers pricing — Cloudflare Docs — the pricing page the README links for the Workers Paid requirement.
Back to: Coding playbooks hub · Also: OpenCode Browse: agents use your real browser