llms.txt
# Clearcote
> Clearcote is a de-Googled Chromium build with engine-level fingerprint controls. It presents one
> coherent, plausible browser identity instead of an accidentally unique one, and is a drop-in for
> Playwright & Puppeteer. The open build has no opaque binaries: every change is a readable patch and
> every release is reproducible and GPG-signed.
Site: https://www.clearcotelabs.com
Repository: https://github.com/clearcotelabs/clearcote-browser
License: BSD-3-Clause (the open build and the SDKs)
Status: pre-release. Open build: Chromium 150 (150.0.7871.114, v0.1.0-pre.23, 2026-09-28). Licensed build (Free with GitHub and Pro): Chromium 155 (155.0.8059.39 r45, 2026-10-19); Pro can also pin 154, 153, 152, 151 and 150, Free with GitHub always runs the latest. Windows x64 + Linux x64. SDK: clearcote 0.54.0 on npm + PyPI + NuGet. Docker: teamflatearth/clearcote (SDK 0.54.0). Profile Manager desktop app 0.18.0 (Windows, Linux and macOS). Full docs for agents in one file: https://www.clearcotelabs.com/llms-full.txt
## What it is
- An independent project. Not affiliated with Google, Chromium, or any commercial browser.
- Built on ungoogled-chromium (Google services/telemetry removed) + a patch set. The open build's patches are public; the licensed build adds patches that are not published, so it cannot be rebuilt from public source.
- Identity controls are compiled into the C++ engine, not injected via JavaScript.
- The persona is the same on every site, like one real machine; canvas and WebGL readback noise is derived per site (farbling-style), so render hashes differ across domains.
- Install it as an SDK and it downloads and SHA-256-verifies the browser: the open build without a licence key, the latest licensed build with one.
## Coherent persona
A single `--fingerprint` seed derives one internally consistent persona for the platform you present (the SDK defaults to the host OS: Windows or Linux; a macOS UA and a best-effort Android persona on request): correlated CPU/RAM tier, screen geometry, color depth, GPU, media devices, codecs, speech voices and WebGPU/WebGL coherence. Language and timezone come from `acceptLanguage` / `timezone` or `geoip`, not the seed. Hardware-class properties stay constant for the session while canvas and WebGL readbacks remain per-site farbled. Without a seed there is no farbling.
## Current controls
Canvas 2D, WebGL renderer + getParameter table (capped at what the real driver supports), WebGPU adapter info/limits, AudioContext metadata (sample rate / latency), fonts, timezone, Accept-Language, navigator.languages, Intl locale, speech voices (including the Google network voices a Chrome of that version lists, 153 r27), UA + UA-CH, hardwareConcurrency, deviceMemory, processor-speed reading, script memory ceiling, screen geometry, storage quota, MediaCapabilities, enumerateDevices, webdriver/headless hints, closed shadow roots, WebRTC proxy-IP, getBattery, navigator.connection, keyboard layout map, getScreenDetails, CSS pointer/hover media, navigator.share, URL drive-letter handling, humanized input, optional Widevine / EME (DRM) via an opt-in CDM fetch, optional in-browser AI agent, and optional real-GPU canvas bridge. Client rects and rendered audio are reported truthfully (not perturbed).
Locale is coherent: `Accept-Language`, `navigator.language`, the full `navigator.languages` array, `Intl.DateTimeFormat`, and `Number.toLocaleString` all follow one language list.
## Key binary flags
Licensed-only switches are marked (licensed, engine revision); the open build ignores them.
- `--fingerprint=<seed>` master seed. Same seed => same identity on every launch on the same machine and browser version (only the `navigator.connection` speed estimate follows the real network). The claimed GPU comes from the maker of the machine's real graphics card; from licensed 154 r36 that maker can change the rest of the hardware too, so a seed differs between an NVIDIA machine and an Intel, AMD or GPU-less one. From licensed 154 r37 the card is one of a range as common as in real browser traffic, and a machine without a graphics card claims Intel or AMD integrated graphics (Intel only on r36). Pin the maker with `--fingerprint-gpu-host-vendor`; keep r36 identities with `--fingerprint-schema=3`, pre-r36 ones with `--fingerprint-schema=2`. Docs: https://www.clearcotelabs.com/docs/fingerprint#seed-across-machines
- `--fingerprint-platform=windows|linux|macos|android` (`macos` = UA/UA-CH only; `android` = best-effort mobile persona: mobile UA/UA-CH, touch, mobile viewport/pointer/orientation, no PDF plugin, Mali/Adreno GPU)
- `--fingerprint-platform-version=<v>`
- `--fingerprint-brand=Chrome|Edge|Opera|Vivaldi`
- `--fingerprint-brand-version=<v>`
- `--fingerprint-tls-profile=chrome-<major>|native` (the SDK's `tlsProfile` default `match-persona` follows brandVersion)
- `--fingerprint-gpu-vendor=<s>` / `--fingerprint-gpu-renderer=<s>`
- `--fingerprint-webgpu-vendor=<s>` / `--fingerprint-webgpu-architecture=<s>` / `--fingerprint-webgpu-device=<s>` / `--fingerprint-webgpu-description=<s>`
- `--fingerprint-hardware-concurrency=<n>` / `--fingerprint-device-memory=<gb>` (150+, open and licensed: bucketed, capped at 32; the older open 149 build caps at 8) / `--fingerprint-color-depth=<n>` / `--fingerprint-device-pixel-ratio=<r>` / `--fingerprint-max-touch-points=<n>`
- `--fingerprint-screen-width=<px>` / `--fingerprint-screen-height=<px>` / `--fingerprint-avail-width=<px>` / `--fingerprint-avail-height=<px>`
- `--fingerprint-location=<lat,lng>`
- `--fingerprint-profile=<gzip+base64 JSON>` (both builds; applies in full on licensed 151 r19+)
- `--fingerprint-storage-quota=<MB>`
- `--fingerprint-schema=1|2|3|4` (licensed, 151 r19; 4 is the default from 154 r37, 3 derives what 154 r36 did, 2 what 153 r29 to 154 r35 did) and `--fingerprint-gpu-backend-real` (licensed, 151 r19)
- `--fingerprint-gpu-host-vendor=nvidia|intel|amd` the graphics maker a persona derives its identity for, instead of the detected one (licensed, 153 r28; no SDK option, pass it in `args`)
- `--fingerprint-gpu-draw=<n>` draws the claimed graphics card again: another real model of the same maker and class, with WebGL and WebGPU to match, the same `<n>` giving the same card and nothing else changing; meant for launches without a seed, which otherwise all claim one card; `--fingerprint-schema=4` (the default) only, and an explicit `--fingerprint-gpu-vendor/-renderer` still wins (licensed, 154 r38)
- `--fingerprint-passthrough` no persona, for troubleshooting (licensed, 152 r22)
- `--disable-fingerprint-voices` keep the host's own voices (licensed, 152 r22)
- `--allow-third-party-cookies` (licensed, 152 r22; needed only before 154 r36, which allows third-party cookies by default as Chrome does) and `--block-third-party-cookies` (licensed, 154 r36+; blocks them)
- `--transparent-proxy` hides the proxy from request headers and connection timing (licensed, 152 r22)
- `--timezone=<IANA>`
- `--accept-lang=<list>` plus `--lang=<primary>`
- `--webrtc-ip=<ip>`
- `--disable-gpu-fingerprint`
- `--disable-gpu-string-spoof` / `--disable-canvas-noise` (licensed, 150 r12)
- `--disable-fingerprint-noise`
- `--fingerprint-color-scheme=light|dark` the persona's light/dark preference; with a seed and no override the persona picks one (about one in three dark), and CSS, matchMedia, the Sec-CH-Prefers-Color-Scheme header and system colours follow it (licensed, 154 r32)
- `--fingerprint-reduced-motion=reduce|no-preference` the reduced-motion preference; CSS, matchMedia, the `Sec-CH-Prefers-Reduced-Motion` header and the smooth-scrolling default follow it together; with a seed and no override the persona reports no-preference, as most desktops do, and without a seed the host setting applies (licensed, 154 r38)
- `--widevine-cdm-path=<dir>` registers a Widevine CDM in every profile at startup; the SDK passes it for a `widevine` launch from 0.41.0 (licensed, 154 r32)
- `--disable-runtime-suppression` restores stock DevTools Runtime behaviour (console/pageerror events, Playwright `setContent()`, `exposeFunction()` after a navigation) for debugging; the SDK's `stock_runtime` adds it (licensed, 154 r32)
- `--disable-genuine-font-faces` keeps the built-in lookalike for every family a Windows persona lists even when the genuine font is installed (licensed, 154 r32)
- `--canvas-bridge-url=ws://host:port` / `--canvas-bridge-auth=user:secret` / `--canvas-bridge-mode=off|all|allow|deny` / `--canvas-bridge-allow=a.com,b.com` / `--canvas-bridge-deny=a.com,b.com` / `--canvas-bridge-fallback=block|local`
- `--agent-llm-url=<OpenAI-compatible base URL>` / `--agent-llm-key=<key>` / `--agent-model=<provider/model>` (a task needs all three; the agent asks for a JSON reply in plain text, so `--agent-tool-mode` currently has no effect)
- `--webrtc-ip-handling-policy=disable_non_proxied_udp` WebRTC leak-proof floor (on the open build, `--webrtc-ip` / geoip lifts it; the licensed build blocks WebRTC UDP egress regardless)
- `--load-extension=<dirs>` / `--disable-extensions-except=<dirs>` load unpacked extensions
- `--fingerprinting-canvas-measuretext-noise` and `--fingerprinting-client-rects-noise` are INERT (names kept in the binary; nothing reads them); `--fingerprinting-canvas-image-data-noise` is inert on the licensed build from 152 r21 and a fixed shuffle on the open build — use `--fingerprint` instead
- The full, annotated list is on https://www.clearcotelabs.com/docs/fingerprint and in llms-full.txt.
## Launch defaults (SDK)
The SDK applies coherent defaults you can override:
- The Privacy Sandbox APIs stay ON (the default persona presents as Google Chrome, which ships them). `disable_privacy_sandbox=True` / `disablePrivacySandbox: true` turns off Topics, FLEDGE, Shared Storage, Private Aggregation and Fenced Frames for a de-Googled persona; WebUSB is not affected.
- WebRTC defaults to `disable_non_proxied_udp`; only an explicit `--webrtc-ip-handling-policy` in `args` overrides it. With that policy and no `webrtc_ip`, a page gets no ICE candidates at all, so behind a proxy use `geoip` (or `webrtc_ip`): from r45 the licensed build then looks like a network that blocks UDP to STUN (local candidates, no public address; earlier builds reported the proxy's address). Use `socks5_udp` for real UDP through a SOCKS5 proxy.
- With no `timezone` and no `geoip`, the timezone follows the language (en-US -> America/New_York). The persona platform defaults to the host OS and the brand to Google Chrome.
- Playwright's `--enable-automation` and `--enable-unsafe-swiftshader` are dropped by default. Pass your own `ignore_default_args` / `ignoreDefaultArgs` to override.
- QUIC / HTTP-3 is disabled when a proxy is set, so no UDP egresses around a TCP-only SOCKS5/HTTP proxy — coherent with proxied Chrome.
- Proxy credentials go to the engine on the licensed build: SOCKS5 username/password (RFC 1929, 151 r14+) and HTTP(S) proxy auth (151 r19+, Python & Node) so the page cache stays on. `license_through_proxy` routes only the licence slot calls through the proxy; the build lookup and download connect directly. Separate `username` / `password` fields work in every SDK version; since SDK 0.31.1 credentials written inside the proxy address (`socks5://user:pass@host:port`) work too.
- `launch()` (Python sync and Node) runs on a throwaway profile, deleted on close; `new_context()` returns that same context. `ephemeral_profile=False` / `ephemeralProfile: false` gives the old incognito Browser.
- A one-line coherence warning is printed to stderr for incoherent option combos (Python and Node; silence with `quiet` / `CLEARCOTE_NO_WARN`); since 0.41.0 that includes a one-time warning when a local launch claims Linux on a Windows host (Direct3D caps the WebGL/WebGPU limits, so a Linux persona there reports limits no Linux machine has). The engine does not forward console or page-error events to automation clients, by design; `stock_runtime=True` / `stockRuntime: true` / `StockRuntime = true` (or `CLEARCOTE_STOCK_RUNTIME=1`) restores them for a debugging run on licensed 154 r32+ (local and Docker launches; off by default because pages can observe it).
- Headed launches default to no emulated viewport (`no_viewport` / `viewport: null`) so `window.innerWidth` matches the real OS window. Headless launches get a realistic display (`--screen-info`: the persona's screen, else a real desktop size) and a window fitted to it before the first page; from 0.42.0 that holds on every platform even when a persona does not take effect. Your own window switch (`--window-size`, `--window-position`, `--start-maximized`) keeps the display and skips only the fit (in `serve()` a size switch leaves geometry entirely to you); your own `--screen-info`, `viewport` or `screen` takes the display over. On a Linux server without a window manager (Xvfb), headed windows are fitted the same way (0.42.0). On a Linux host a Linux persona's WebGL renders through Mesa over EGL (`--use-angle=gl-egl`) headless and headed alike when `libegl1` is present (0.42.0), so both modes show one WebGL surface; your own `--use-angle` / `--use-gl` wins and still gets `--ignore-gpu-blocklist` headless.
- On licensed 154 r32+ (SDK 0.41.0+): the persona switches (seed, overrides, proxy credentials, canvas-bridge token) reach the browser through its environment (`CLEARCOTE_PERSONA_ARGS`) instead of its command line, so they are not in the process list (`persona_env=False` / `personaEnv: false` / `PersonaEnv = false` or `CLEARCOTE_PERSONA_ENV=0` keeps the command line); contexts the SDK creates on a local launch leave Playwright's colour-scheme emulation off so the persona's light/dark choice reaches the page (`color_scheme` / `colorScheme` / `ColorScheme` to emulate one anyway).
- Overlapping `--enable-features` / `--disable-features` (the SDK's defaults plus your own) are merged into a single flag each.
## Recent changes (SDK 0.26 - 0.41, licensed builds 152 - 154)
- Licensed 155 r45 (2026-10-19): profiles agree with themselves on more surfaces (desktop touch events off, video decoding answers consistent across APIs, every raw pointer update carries its own sample); with a WebRTC IP or geoip, WebRTC behind a proxy looks like a network that blocks UDP to STUN (no public address, neither the proxy's nor yours); visible Windows fullscreen covers the profile's screen also from a maximized window and on single-monitor hosts; Windows profiles draw their own Office font set (existing profiles' font lists change once; personaSchema: 4 keeps r44's identity); everything from r44 included, Windows and Linux both on r45.
- Licensed 155 r44 (2026-10-17): humanized input can run inside the browser itself (clicks, held drags, typed runs performed by the engine with the profile's timing); a fresh page is entered from the window edge at the profile's mouse rate; fullscreen on a visible Linux browser reports the profile's screen; graphics, media, touch, audio, authenticator and Bluetooth answers follow the profile; everything from r42 included, Windows and Linux both on r44.
- Licensed 155 r42 (2026-10-13): Chromium 155, the newest browser generation, with everything from r41; on Windows, graphics-heavy pages can use the shader features an ordinary Chrome offers on the same card; Windows and Linux both on r42.
- Licensed 154 r41 (2026-10-13): general maintenance: security, compatibility and reliability refinements; Windows and Linux both on r41.
- Licensed 154 r40 (2026-10-12): engine-made humanized clicks rest briefly before pressing and hold like a hand, starting from where the pointer is; a humanized click by selector refuses hidden, covered or off-screen elements; mouse input sent straight to the browser is handled as in Chrome unless you launch with `--humanize-raw-input=on`; PRO licence checks hardened further; Linux ships the complete bundled font set again.
- Licensed 154 r39 (2026-10-12): stronger licence enforcement across the browser and its service processes; long-running licensed sessions stay healthy after launch authorization completes; Windows sandboxed renderer and network processes start reliably. The corrected build passed native Windows and Linux, Linux Docker, sandboxed and non-sandboxed, and hosted-gateway checks before publication.
- Licensed 154 r38 (2026-10-11): headless fullscreen fills the whole screen, and leaving it returns the window to its maximized size; fullscreen also works while an automation client such as Playwright keeps the page focused; Linux with a visible window draws canvases the same way as headless, so a profile renders the same in both modes; on Windows servers without audio output or Windows Hello, speech synthesis plays silently and a passkey prompt waits like an unanswered dialog instead of failing at once; under persona schema 4 (the default) network information starts from realistic values for a browser in use for a while, audio output latency follows the page's latency hint as on Windows, Windows profiles report no taskbar about as often as real machines and four Linux graphics card names are refreshed, while `--fingerprint-schema=3` and `=2` keep r37's values; with a profile, reduced motion is reported the way most desktops report it; new `--fingerprint-gpu-draw=<n>` and `--fingerprint-reduced-motion=reduce|no-preference`; `page.setContent()` works on local launches. Windows and Linux on the same revision.
- Licensed 154 r37 (2026-10-10): profiles draw their graphics card from a wider range of real models of this computer's graphics maker, each as common as in real browser traffic; a computer without a graphics card reports integrated graphics from either maker that ships it. Existing profiles keep the rest of their device; `--fingerprint-schema=3` keeps a profile's r36 card. Headless: a file chooser a page opens stays open for a few seconds and is then cancelled, and window.print() behaves like a print preview the user closes, instead of both answering within milliseconds.
- Licensed 154 r36 (2026-10-09): profiles draw their graphics card from a range of real models of this computer's graphics maker instead of one model per maker, and on a computer with a discrete card they no longer get entry-level hardware (small laptop screen, touch screen); an existing profile keeps everything else but its card can change (and on discrete-card machines its processor, memory, screen and touch values), so pin r35 to keep one exactly; a screen size you set yourself is reported the same way everywhere a page reads it; headless on Windows, a display scale above 100% keeps the screen at least as large as its available area and a full-screen window has the shape of a maximized one; headless no longer refuses every permission request the moment it is asked; third-party cookies are allowed by default as in Chrome, with blocking available as an option. Windows and Linux on the same revision.
- Licensed 154 r35 (2026-10-08): profiles report the space a taskbar or panel takes the way real machines do (most Linux profiles none, Windows 11 profiles varying between the usual sizes including none); nothing else about a profile changes, so an existing profile keeps its device. Windows and Linux on the same revision.
- Licensed 154 r34 (2026-10-08): reading pixels back from a WebGL drawing matches what the same drawing exports as an image, including when the browser reports the computer's real graphics card; a profile that pins the screen size reports a window height that agrees with what a mouse event implies; a launch refused over a licence problem leaves no temporary profile folder behind.
- Licensed 154 r33 (2026-10-08, Windows only): fixes r32 tabs crashing when the browser runs with its sandbox on (`clearcote serve`, hosted browsers); otherwise the same as r32.
- Licensed 154 r32 (2026-10-08): a profile can prefer dark mode on its own and the whole browser stays consistent with it; on a Windows profile text has the line heights and common font widths of
