kitesurf-bridge

Controla Cloudflare Kitesurf — el navegador pensado para agentes que se ejecuta en isolates de V8 sobre Cloudflare Workers — desde cualquier sitio. Cero dependencias, sin Chrome local.

Incluye cuatro formas de usar un mismo motor:

Los comandos de instalación que aparecen abajo utilizan la especificación de GitHub, que funciona hoy sin cuenta de registro. Una vez publicado en npm como @truenin/kitesurf-bridge, cada github:TrueNix/kitesurf-bridge se cotar a @truenix/kitesurf-bridge.

npx -y github:TrueNix/kitesurf-bridge markdown https://news.ycombinator.com

Esto rederiza una página real en un motor de navegador real, en la red de Cloudflare, sin navegador instado localmente y sin token de API.

Por qué esto existe

Kitesurf no es de código abierto y no puedes ejecurlo en tu máquina. Cloudflare dice que piensan liberar su "una vez que estemos listos", y e in use e el fin establecido es que los clientes "despleguen su propia versión de Kitesurf en sus propiadas cuentas" — justo en Workers.

Tampoco exite un Kitesurf local en el bucle de desarollo: wrangler dev lanaza tu Sin server local, no Kitesurf. Kitesurf solo existe detras de browser=kitesurf en los endpoints remosot.

La pregunta práctica no es si puedo ejecurlo localmente, sino si puedo conducirlo* desde código local. Este paquete es ese puente.

Instalación

Como servior MCP

claude mcp add kitesurf -- npx -y github:TrueNix/kitesurf-bridge mcp

{
  "mcpServers": {
    "kitesurf": {
      "command": "npx",
      "args": ["-y", "github:TrueNix/kitesurf-bridge", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "kitesurf": {
      "command": "npx",
      "args": ["-y", "github:TrueNix/kitesurf-bridge", "mcp"],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "CLOUDFLARE_API_TOKEN": "your-browser-run-token"
      }
    }
  }
}

Herramientas peridas: kitesurf_markdown, kitesurf_text, kitesurf_html, kitesurf_links, kitesurf_screenshot, kitesurf_evaluate, kitesurf_accessibility_tree, kitesurf_probe.

Como plugin de DSH / Cordis

# in an agent preset composition
- '@truenix/kitesurf-bridge/cordis':
    cli: npx -y github:TrueNix/kitesurf-bridge
    timeoutMs: 120000

El plugin registra las mismas herramientas en el host. Deliberadamente utiliza el CLI: un host dinámico de Cordis no tiene acceso a WebSocket, fetch ni node:*, por lo que no se puede abrir CDP dentro del sandbox. Ver cordis/plugin.mjs.

Como librería

npm install github:TrueNix/kitesurf-bridge

import { withSession } from '@truenix/kitesurf-bridge';

const md = await withSession({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

CLI

kitesurf-bridge <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JS runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Endpoint + engine capability report
  mcp                Run as an MCP server on stdio

Opciones útiles: --main, --raw, --full, --width, --height, --json, --endpoint, --account, --token, --timeout.

Endpoints

Establece CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN (o CF_*) para cambiar. Proporcionar un id de cuenta sin token es un error grave, no una degradación silenciosa al playground compartido.

[!WORDNOTE] El playground es un recurso gratuito, compartido y sin autenticación, sin SLA. Vale para evalución y trabajo local de agente — no cree producción en él.

Aspectos que rescúnt saer sobre Kitesurf

Esto está confirmado contra el servicio en directo, no es copiado de documentación. kitesurf-bridge probe lo reca.

Kitesurf no usa V8 para ejecutar el script de la página: usa Boa, un motor de JavaScript en Rust. Boa impone un línite de recursiva mucho más bajo y lanza RuntimeLimite... Exceeded\] in a RuntimeLimit: exiteded... recursive calls**. Un recorrido recursivo natural por el DOM muere en cualler página grande (Wikipedia, sitios of doces). Por eso, el conversor Markdwn de este paquete recorre el DOM con pila explícita, mantendo la profudidad de evación en JS en O(1). So usas kitesurf_evaluate, prefiere expresiones iteritig.

Los fallos de navegación llegn como códigos de estado del edge of Cloudflare, no como errors de CDP. Page.navigate devuelve un frame/loaderId normal incuso para un host little and roto, and no se fira Network.loadingFailed. Un dominio that no exists appears like HTTP 530, an origin rot as 520, deprando un own document of relleno of ~16 charactererse. Confión" Page.gate and black and hand un agent to success — "For eso este paquete cla clasificca outcomes del dominio Network y lanza cuando un >=400 status arrives with an empty document, pero still the "orig" returns "real page de errors" (with status) that have readable content. Capacid flags (veriados):

For those, use instead Browser Run's default Chromium browser.

Performance trade (Cloudflare's own figures): Kitesurf uses 3–7× less CPU and memory than a warm Chromium, but 1.7–1.8× more wall-clock speed. That day is on Cloudflare's bill for spiky cloud agent workloads — it saves nothing on your own de los usuarios. If you just want local browser automation and already have Chrome, local Playwright is faster and supports WebGL and video.

Zero dependencies

package.json has an empty dependencies block, including for the WebSocket transport.

Node's global WebSocket (WHATWG) cannot send request headers, and the account endpoint needs Authorization: Bearer …. undici is not importable as a standalone module. So src/ws.mjs implements the RFC 6455 client directly over node:http(s) — handshake, masking, continuation fragments, 64-bit lengths, ping/pong, close — which is everything CDP needs, with header support.

Tests

npm test                        # live tests against the playground
KITESURF_SKIP_NETWORK=1 npm test   # offline only

The suite hits the real service on purpose: the interesting failures (Boa's recursion limit, wrapper truncation, edge status codes) only appear against the real thing.

Requirements

Node ≥ 18. No dependencies, no API token, no build step.

License

MIT