Skip to content
Webfold Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Headless and CDP

Run Webfold's CDP subset server for Playwright and Puppeteer, and the intercepting proxy.

webfold headless run <url> [--stealth] [--proxy host:port]
webfold headless serve [port] [--stealth] [--profile DIR]
webfold headless capabilities
webfold proxy [port]

CDP server

headless serve starts a Chrome DevTools Protocol endpoint on ws://127.0.0.1:<port> (default port 9222), backed by Webfold’s own page and layout engine rather than Chromium.

Puppeteer

const browser = await puppeteer.connect({ browserWSEndpoint: "ws://127.0.0.1:9222" });

Playwright

const browser = await chromium.connectOverCDP("ws://127.0.0.1:9222");

--stealth enables the navigator fingerprint patches. --profile DIR keeps the default context’s cookies in DIR across runs; set WEBFOLD_PROFILE_SEED to seal them.

What is and is not supported

Webfold implements a subset of CDP. Every method is exactly one of implemented, a named no-op, or unsupported (JSON-RPC error -32601). There is no silent-success fallback. Ask the server what it supports:

webfold headless capabilities     # JSON: implemented / no-op / unsupported
  • Implemented areas include page lifecycle and navigation events, Runtime evaluation, DOM with layout geometry, Input with focus and form semantics, Network and Fetch for document requests, Emulation, screenshots, Targets and browser contexts, Accessibility, CSS and DOM snapshots.
  • Page.printToPDF is unsupported, and some methods are named no-ops. Screenshots use Webfold’s own renderer, not Chrome’s.
  • Page script runs on Webfold’s JavaScript engine, not V8. Playwright and Puppeteer locators, fill, click, check, selectOption, page.content() and $eval work through an interpreter for the in-page functions those clients send. A function outside the supported surface returns an error.

Intercepting proxy

webfold proxy [port] starts an intercepting HTTP/HTTPS forward proxy (default 127.0.0.1:8080) with block and pause rules and traffic logging. Keep it on a controlled interface.