Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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

Run it locally first

Clone the repository, install dependencies with the lockfile, and start the engine:

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:

  1. 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.
  2. Deploy from the repository root with pnpm run deploy. The command builds with Bazel and uploads with Wrangler, using the account from wrangler login or the CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN values; without --name, the Worker name is kitesurf.
  3. 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

Related playbooks

Sources

Back to: Coding playbooks hub · Also: OpenCode Browse: agents use your real browser