nokk
A stealth headless browser for AI agents: load pages behind Cloudflare/Turnstile, read and interact with them, all over MCP.
Open pages —
openloads a URL, waits for it, and returns the finalurlandtitle(a Cloudflare challenge is solved automatically unless auto-solve is off).Get past bot checks —
challenge_statereports whether the page is gated (Cloudflare interstitial, Turnstile widget, AWS WAF, etc.) and whether it is solvable;solve_challengeclears it with an optional timeout.Read content —
read_text(visible text),read_html(post-script HTML),links(all absolute links), orsnapshotfor a compact numbered outline of headings, text, links, buttons and form fields.Interact —
clickelements andfillform fields by snapshot ref (e12) or CSS selector, firing input/change events as a person would.Run custom JS —
evaluateexecutes an expression in the page and returns the (awaited) result as JSON.Reset state —
resetcloses the session, dropping cookies and page state so the nextopenstarts fresh.Narrow scopes for all readers —
snapshot,read_textandread_htmlaccept an optionalselectorto target a single element, andsnapshottakesmax_charsto cap output size.
Automatically clears Cloudflare challenges (Turnstile invisible widgets, managed interstitials, and the interactive 'Verify you are human' checkbox) while browsing, thanks to a Chrome-matching TLS/HTTP and JavaScript fingerprint. Options control the time budget for solving, whether to stop as soon as a cf_clearance cookie is obtained, and whether to auto-solve on every navigation over CDP.
A stealth headless browser engine in Rust. Passes Cloudflare without Chromium.
Real V8 and a DOM, a Chrome TLS/HTTP fingerprint (JA3/JA4) and JS-level stealth, driven over the Chrome DevTools Protocol: Puppeteer and Playwright connect as usual. Also an MCP server for AI agents.
scrapingcourse.com's Cloudflare test page, one run from a home connection; medians across sites are in the tables below.
The nøkk is a shapeshifting water-spirit of Norse myth that takes on a familiar shape to pass unnoticed. This one takes the shape of Chrome.
Install
pip install nokk # Python: the prebuilt binary is in the wheel
npm install @koloss777/nokk # Node: run it with `npx nokk`
docker run --rm -p 9222:9222 ghcr.io/koloss777/nokk:latestNo browser to download. Prebuilt for Linux (x86_64, ARM64), macOS on Apple Silicon and Windows x64; anything else builds from source.
Related MCP server: Airbrowser
Quick start
# Load a page behind Cloudflare, clear the challenge, print what is behind it
nokk --load https://www.scrapingcourse.com/cloudflare-challenge --solve-challenge 30 \
--eval "document.querySelector('h2').textContent.trim()"
# Or run the CDP server and drive it from any client
nokk --port 9222 --auto-solve # ws://127.0.0.1:9222/devtools/browser/nokkimport nokk
from playwright.sync_api import sync_playwright
with nokk.launch(auto_solve=True) as server, sync_playwright() as pw:
page = pw.chromium.connect_over_cdp(server.ws_endpoint).new_page()
page.goto("https://www.scrapingcourse.com/cloudflare-challenge")
print(page.title())For AI agents, uvx nokk-mcp runs it as an MCP server.
Puppeteer, Node, sessions and the Cloudflare options are below.
Why nokk
Puppeteer and Playwright drive a real Chromium, and anti-bot systems spot it through
navigator.webdriver, CDP artifacts and a headless TLS handshake. nokk is built to
look like Chrome from the TLS handshake to the JavaScript environment, and has no
rendering engine at all.
nokk 0.1.35 | Chrome 151 (Puppeteer / Playwright) | |
Start until CDP answers | ~0.05 s | ~0.2 s |
Idle memory (PSS) | ~60 MB, 1 process | ~330 MB, 12–14 processes |
Cloudflare solve, median wall time | 12.4 s | 12.4 s |
Slowest solve | 15.6 s | 27.8 s |
CPU per solve | 6.4 s | 9.5 s |
Peak memory per solve | ~570 MB | ~720 MB |
Solved | 24/24 | 24/24 |
TLS fingerprint (JA3/JA4) | matches Chrome 151 | Chrome |
Screenshots, PDF, layout | no | yes |
CDP coverage | the common path | full |
Measured on nokk 0.1.35, an 8-core Linux box, October 2026. Cloudflare row: 8 production sites × 3 runs through one proxy, nokk with --until-clearance, Chrome driven by a checkbox-clicking harness; a solve counts only if the site then opens with the cookie.
Not for you if you need screenshots, PDFs, layout or paint, or the whole Playwright/CDP surface: nokk has no rendering engine by design, and its CDP coverage is the path Puppeteer and Playwright use for navigation and scripting.
Measured on public pages
Three runs per page from the CLI with --solve-challenge 30 and no proxy, on an 8-core
Linux box (October 2026). The time is the whole command, from process start to the printed
result. Run them yourself with tools/cf-check.sh.
Page | Challenge | Solved | Median | Slowest |
| invisible Turnstile widget on a live site | 3/3 | 7 s | 9 s |
| managed interstitial | 3/3 | 5 s | 7 s |
| managed widget | 3/3 | 7 s | 8 s |
| non-interactive widget | 3/3 | 3 s | 4 s |
| interactive interstitial with a checkbox | 3/3 | 10 s | 11 s |
On production sites behind Cloudflare the result is in the comparison above: 8 sites, 24 of 24 solved. Those sites are not named here.
Usage
Command line
nokk --fetch https://tls.browserleaks.com/json # Chrome TLS + HTTP/2 fingerprint
nokk --load https://example.com --eval 'document.title' # run the page, query the DOM
nokk --load https://quotes.toscrape.com --dump-requests # every request the page makes
nokk --load https://target --proxy socks5://host:1080 # through a proxy
nokk --load https://target --solve-challenge 30 --json # one JSON result: status, challenge, cookies
nokk --port 9222 --rotate-fingerprint --geoip-timezone # CDP server, a machine per contextAd, analytics and tracker requests are dropped by default; --allow-trackers loads them.
Anti-bot vendors are never blocked, because they must run to hand out a token.
Puppeteer
import puppeteer from 'puppeteer';
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/nokk', // nokk --port 9222
});
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());Node and Python
Both packages carry the prebuilt binary and start the CDP server for you.
const server = await require("@koloss777/nokk").launch({ autoSolve: true });
// server.wsEndpoint -> puppeteer.connect / chromium.connectOverCDPwith nokk.launch(auto_solve=True) as server: # or: await nokk.launch_async()
... # server.ws_endpoint -> connect_over_cdpcrawl4ai, Scrapy, Playwright MCP and other CDP tools
Anything that drives Chrome over CDP can drive nokk instead. crawl4ai, stopped by
Cloudflare with its own Chromium, gets the page behind it through nokk:
BrowserConfig(browser_mode="custom", cdp_url=server.ws_endpoint). Scrapy
(scrapy-playwright's PLAYWRIGHT_CDP_URL) and Playwright MCP (--cdp-endpoint)
work the same way. See docs/integrations.md.
For AI agents (MCP)
nokk runs as a Model Context Protocol server, so an agent such as Claude Desktop or Claude Code browses through the fingerprinted engine. With uv nothing needs installing first:
{ "mcpServers": { "nokk": { "command": "uvx", "args": ["nokk-mcp", "--rotate-fingerprint"] } } }Without uv: pip install "nokk[mcp]", then "command": "python", "args": ["-m", "nokk.mcp"].
Tools: open, snapshot, read_text, read_html, click, fill, evaluate, links, solve_challenge,
challenge_state, reset.
Cloudflare challenges
nokk clears Turnstile by itself: the invisible widget, the managed interstitial and the interactive Verify you are human checkbox. Nothing is configured per site. Where a widget needs a press, the engine presses it like a person would.
--solve-challenge Nsets the time budget, and--fail-on-challengeexits3if a gate is still up.--until-clearancestops at a freshcf_clearanceand skips the heavy page behind the gate.--auto-solvedoes the same for everypage.goto()over CDP;Nokk.solveChallengedoes it on demand.A
cf_clearancefrom a real browser can be imported, because nokk's JA4 matches Chrome 151.
Details, the CDP methods and events: docs/cloudflare.md.
Persistent sessions
--session-store ./sessions saves each named session's cookie jar, cf_clearance included,
to disk and reloads it in a new process. Warm a session once and reuse it instead of
solving the challenge on every run. See docs/sessions.md.
Rotating fingerprints
--rotate-fingerprint gives every browser context its own coherent machine: TLS emulation,
User-Agent, client hints, platform, screen and WebGL all agree. --geoip-timezone matches the
timezone and languages to the proxy's exit IP. See docs/fingerprints.md.
Builds
Build | What it adds | Where |
light (default) | everything above; canvas and WebGL pixels are synthesised | pip, npm, |
render | real canvas 2D and WebGL rasterisation, about 100 MB more at peak |
|
Prebuilt for Linux x86_64 and ARM64, macOS on Apple Silicon and Windows x64; the render build for Linux x86_64. Docker variants, the archives and building from source are in docs/install.md.
How it works
A Cargo workspace of small crates: a V8 isolate pool, a Chrome-fingerprinted HTTP client on
BoringSSL, an html5ever DOM, the stealth layer and a CDP server. Concurrency is one isolate
per thread with many contexts each, all IO runs on tokio off the isolate threads, and the
JS fingerprint and the TLS fingerprint always agree. More in docs/architecture.md.
Project status
Alpha. The engine is real and end-to-end: V8 executes page JS against a parsed DOM, the fingerprinted transport clears Cloudflare's TLS/HTTP checks, the engine solves Turnstile on live sites — invisible, managed and interactive — and Puppeteer and Playwright connect over CDP to open a page, navigate, and evaluate.
What is not done yet, and where the sharp edges are:
JS-fingerprint hardening is ongoing. Much of the hardening is in place — native
toStringmasking, internals hidden fromObject.getOwnPropertyNames,navigator/screenas real prototype instances, an IP-coherent timezone, and per-context coherent fingerprint rotation, Web Workers, canvas/WebGL/WebGPU/audio with Chrome's pixels and samples, Trusted Types and CSP. nokk solves Cloudflare's challenges today, and the comparison against Chrome section by section is how the remaining tells get found; it is not yet a match for a dedicated fingerprinting suite like CreepJS. See the roadmap.CDP coverage is the common path, not the whole protocol. Puppeteer and Playwright connect over CDP: navigation,
evaluate,$/$eval/$$eval,title(),url(), new pages and CDP sessions are tested; less-common domains are not implemented yet.Per-context cookie isolation and per-session persistence work (each browser context gets its own jar; named sessions persist across runs); per-host / per-proxy / global connection limits are not yet enforced (Phase 7).
No rendering — screenshots, PDF, and layout/paint are out of scope by design.
See ROADMAP.md for the phased plan and the concrete hardening backlog.
Contributing
Issues and PRs are welcome — the hardening backlog in the roadmap is a good place to start. Before sending a change:
cargo fmt
cargo clippy --all-targets
cargo testLicense
Licensed under either of MIT or Apache-2.0 at your option.
Unless you explicitly state otherwise, any contribution you submit for inclusion in this work, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.
Available Tools
11 toolschallenge_stateA
Report whether the current page is behind a bot check. kind is "none"
when the page itself is shown, else the kind of check ("cloudflare-interstitial",
"turnstile-widget", "aws-waf" and others); solvable says whether
solve_challenge can clear it.
Inputs: no named parameters. Returns: result
clickA
Click an element: a ref from snapshot or the first match of a CSS
selector. Returns true; fails when nothing matches or the ref is stale.
Inputs: target (required). Returns: result
evaluateA
Run a JavaScript expression in the current page and return its value as JSON (a promise is awaited). For data the other tools do not read.
Inputs: expression (required).
fillA
Type value into a form field: a ref from snapshot or the first match
of a CSS selector (its input and change events fire, as when a person
types). Returns true; fails when nothing matches or the ref is stale.
Inputs: value (required), target (required). Returns: result
linksA
Return the absolute addresses of all links on the current page.
Inputs: no named parameters. Returns: result
openA
Load a page in the browser and wait until it has loaded. Returns the final
url and title. A Cloudflare challenge on the way is solved first (unless the
server runs with --no-auto-solve); challenge then reports kind, solved
and remaining ("none" once through). Call this before the other tools.
Inputs: url (required). Returns: result
read_htmlA
Return the HTML of the current page as it is now (after its scripts ran),
or the outer HTML of the first element matching selector. null when no
element matches.
Inputs: selector. Returns: result
read_textA
Return the visible text of the current page, or of the first element
matching selector. null when no element matches.
Inputs: selector. Returns: result
resetA
Close the browser session: cookies and page state are dropped, and the
next open starts a fresh one.
Inputs: no named parameters. Returns: result
snapshotA
Show the current page as a compact outline: headings and text in reading
order, and every link, button and form field numbered ([e12]) with its
name, address or value. Pass a ref to click or fill. Far smaller than
read_html; take a new snapshot after the page changes. null when
selector matches nothing.
Inputs: selector, max_chars. Returns: result
solve_challengeA
Solve the Cloudflare challenge on the current page: the "Just a moment..."
page or a Turnstile widget, pressing its checkbox if it shows one. Only needed
when open ran with auto-solve off or a widget appeared later. Returns
status, solved, remaining, title and url.
Inputs: timeout_seconds. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
The reading tools (snapshot, read_text, read_html) overlap in that all return page content, but the descriptions clearly carve out distinct roles — numbered interactive outline vs visible text vs raw HTML — and explicitly recommend snapshot over read_html. challenge_state and solve_challenge are cleanly split into report vs act, and evaluate is explicitly framed as a fallback for 'data the other tools do not read'.
All names are snake_case, which avoids casing chaos, but conventions are mixed: action verbs (open, click, fill, evaluate, reset, solve_challenge) sit alongside bare nouns (snapshot, links, challenge_state). Readable and semi-predictable (nouns for getters, verbs for actions), but not a uniform verb_noun pattern.
Eleven tools is well within the sweet spot for a browser automation server, and each has a clear, non-redundant role in the open → snapshot → act → read lifecycle. Nothing feels padded or missing at the count level.
Core lifecycle (open, solve challenge, inspect, click/fill, reset) is fully covered, but common browser operations like back/forward navigation, key presses, select/hover, and downloads lack dedicated tools. The evaluate escape hatch lets agents work around most of these gaps, so they are minor rather than blocking.
Maintenance
Related MCP Connectors
Undetectable cloud browser sessions for AI agents and scrapers. Navigate, extract, click, captcha.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Browser agents and stealth cloud browsers for AI: run web tasks, fill forms, extract data.
Cloud browsers for AI agents: saved logins, residential IPs, live human takeover, 57 browser tools.
Related MCP Servers
- AlicenseAqualityNot gradedmaintenanceEnables browser automation through Playwright using accessibility tree snapshots instead of screenshots. Supports web scraping, form interactions, testing, and connecting to existing browser sessions with logged-in accounts.238,303 npm5-
- AlicenseAqualityDmaintenanceOpen-source browser automation API with anti-detection for AI agents, web scraping, and automation, providing undetectable Chrome via MCP and REST API with Cloudflare bypass.2412MIT
- AlicenseBqualityAmaintenanceCloakBrowser MCP server for AI agents: Playwright-powered browsing, clean tool forwarding, Docker support, and multi-session HTTP transport.25280 npm178MIT
- AlicenseAqualityDmaintenanceStealth browser automation for AI agents, using source-patched Chromium to bypass bot detection systems like Cloudflare, reCAPTCHA, and FingerprintJS.28Apache 2.0