Docs / Quickstart

Connect over CDP

CrawlFlux exposes a standard Chrome DevTools Protocol endpoint. Any client that speaks CDP — Playwright, Puppeteer, raw WebSocket — can drive it.

1. Get a token

Create one in the console and export it:

shell

export CRAWLFLUX_TOKEN="cf_live_..."

2. TypeScript (Node 18+)

npm

npm i playwright

index.ts

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP("wss://connect.crawlflux.dev", {
  headers: { Authorization: `Bearer ${process.env.CRAWLFLUX_TOKEN}` },
});
const context = browser.contexts()[0] ?? (await browser.newContext());
const page = await context.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close(); // ends the session and stops billing

3. Python 3.9+

pip

pip install playwright

main.py

import asyncio, os
from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(
            "wss://connect.crawlflux.dev",
            headers={"Authorization": f"Bearer {os.environ['CRAWLFLUX_TOKEN']}"},
        )
        context = browser.contexts[0] if browser.contexts else await browser.new_context()
        page = await context.new_page()
        await page.goto("https://example.com")
        print(await page.title())
        await browser.close()  # ends the session and stops billing

asyncio.run(main())

No playwright install step is needed — the browser runs on our side.

Why headers, not query strings

Tokens in ?token= URLs end up in proxy logs, error trackers and shell history. Both connectOverCDP and connect_over_cdp accept a headers option, so the token travels in the WebSocket upgrade request only.

Session lifecycle

A session starts on connect and ends on browser.close() or disconnect.
Idle sessions (no CDP traffic) are terminated after 5 minutes; hard cap 30 minutes per session.
Billing is per second of session time.

Next: running Playwright from Lambda and other serverless runtimes.