terry2010 /surfbird

Kitesurf, self-hosted — unofficial Docker distribution of Cloudflare's headless browser engine for AI agents. CDP + token auth + REST actions (screenshot/pdf/markdown) + MCP tools, all in one container.

★ 1⑂ 1👁 1⑃ 0● 0▤ 1
JavaScriptApache-2.0Created 2026-11-13hub.docker.com/r/terry2010/surfbird
Download: kitesurf 2026.11.9kitesurf-2026.11.9 ↓2026.11.92026-11-14
+0
Daily
1
stars
1
forks
1
watchers
0
prs
0
issues
1
releases

README

Surfbird







Kitesurf, self-hosted. An unofficial Docker distribution of Cloudflare Kitesurf — the experimental browser engine built for AI agents.

 Not affiliated with or endorsed by Cloudflare. Kitesurf is Apache-2.0 licensed.

Kitesurf parses HTML, applies CSS, runs page JavaScript and renders screenshots — no Chrome, no browser container — and speaks CDP, so Puppeteer/Playwright connect as usual. Upstream only supports wrangler dev locally or deploying to Cloudflare Workers (paid). Surfbird packages it for any VPS.

 Images

| Tag | Contents | Use |
|---|---|---|
| terry2010/surfbird:raw | engine only, :8787 | local / behind your own gateway |
| terry2010/surfbird:auth | engine + token auth proxy + optional TLS, :8080 | one-command, exposed |
| terry2010/surfbird:latest | = :auth | convenience default |

Images auto-build daily when upstream cuts a new tag; per-tag pins like terry2010/surfbird:auth-2026.11.8 are also published.

 Quick start

bash
 raw — engine only, no auth. Bind loopback/internal only!
docker run -d -p 127.0.0.1:8787:8787 terry2010/surfbird:raw

 auth — one command, token + REST actions
docker run -d -p 127.0.0.1:8080:8080 -e SURFBIRD_TOKEN=$(openssl rand -hex 24) terry2010/surfbird:auth


 Usage

CDP (Puppeteer / Playwright / chrome-devtools-mcp):

js
puppeteer.connect({
  browserWSEndpoint: "ws://:8787/devtools/browser",       // raw
  // or auth image:
  browserWSEndpoint: "ws://:8080/devtools/browser",
  headers: { Authorization: "Bearer " },
});


REST (auth image only):

bash
curl -H "Authorization: Bearer $TOKEN" \
     -d '{"url":"https://zhuikan.com/repos/terry2010__surfbird","fullPage":true}' \
     http://:8080/screenshot -o page.png

curl -H "Authorization: Bearer $TOKEN" \
     -d '{"url":"https://zhuikan.com/repos/terry2010__surfbird"}' \
     http://:8080/markdown | jq -r .markdown


Endpoints: POST /screenshot | /pdf | /content | /source | /markdown | /evaluate | /batch (one action over up to MAX_BATCH_URLS urls, per-item results), GET /health, GET /openapi.json. /content returns the post-JS rendered DOM; /source returns the original response body ("view source").
All other paths transparently proxy to the engine (landing page, /json/, /rbi/).

JS/TS client: surfbird on npm — new Surfbird(url,{token}).markdown(u) etc., plus sb.batch(action, urls).

 MCP (Model Context Protocol)

Two ways to plug Surfbird into an MCP-capable agent (Claude Code, Cursor, Windsurf, …):

A. surfbird-mcp — thin wrapper (recommended). Exposes our REST actions as MCP tools — including surf_markdown and surf_batch, which stock browser MCPs don't have:

json
{
  "mcpServers": {
    "surfbird": {
      "command": "npx",
      "args": ["-y", "surfbird-mcp"],
      "env": {
        "SURFBIRD_URL": "http://:8080",
        "SURFBIRD_TOKEN": ""
      }
    }
  }
}


Tools: surf_markdown surf_content surf_source surf_screenshot surf_pdf surf_evaluate surf_batch surf_health.

B. chrome-devtools-mcp — full CDP surface. Points straight at t

Latest release

kitesurf 2026.11.9 kitesurf-2026.11.9 2026-11-14
Docker images built from upstream kitesurf 2026.11.9.

| image | pull |
|---|---|
| auth — REST actions + token auth + optional TLS | docker pull terry2010/surfbird:auth-2026.11.9 |
| raw — engine + CDP only | docker pull terry2010/surfbird:raw-2026.11.9 |

Floating tags raw / auth / latest point at this build.
Unofficial distribution — not affiliated with Cloudflare.

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON