---
title: "Headless and CDP"
description: "Run Webfold's CDP subset server for Playwright and Puppeteer, and the intercepting proxy."
---

```sh
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**

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

**Playwright**

```ts
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:

```sh
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.

:::warning
Connecting a CDP client does not establish full browser compatibility. A successful protocol response is not evidence that a requested security policy took effect. Measured behaviour against Playwright and Puppeteer is in `docs/CDP-CONFORMANCE.md` in the repository.
:::

## 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.