# Clearcote — Full documentation bundle (for AI agents & LLMs) > This single file is the COMPLETE Clearcote documentation, flattened for pasting > into an AI coding agent (Claude, Codex, Cursor, etc.) so it has full project > context in one shot. Human docs live at https://clearcotelabs.com/docs and the > short machine summary at https://clearcotelabs.com/llms.txt > > Generated for: Clearcote Browser — open-source, de-Googled Chromium with > engine-level fingerprint controls. Drop-in for Playwright & Puppeteer. --- ## Project facts - Name: Clearcote (internal build codename "clearcoat" — never used publicly) - One-liner: Blend in. Stay clear. - Site: https://clearcotelabs.com - Repository: https://github.com/clearcotelabs/clearcote-browser - License: BSD-3-Clause (Clearcote's own code + patches; upstream keeps its licenses) - Status: pre-release (v0.1.0-pre.2) - Engine: Chromium 149 (pinned 149.0.7827.114) - Platform: Windows x64 (more platforms on the roadmap) - Automation: drop-in for Playwright & Puppeteer via `executablePath` - Identity model: engine-level (C++), coherent, per-site (eTLD+1) "farbling" - Distribution: GitHub Releases, SHA-256 checksummed + GPG-signed - Pinned signing key (ed25519): CA96 F185 F96A 693A EDB3 AC1F CB00 D851 B7A8 6B0F --- ## What it is A stock browser quietly exposes a unique, trackable fingerprint — canvas, WebGL, audio, fonts, locale, hardware and more. Clearcote moves control of those signals INTO THE ENGINE ITSELF, so a session presents one consistent, plausible identity instead of an accidentally hyper-unique one. It is built on ungoogled-chromium (Google integration and telemetry removed) plus a transparent stack of source patches. There is no magic binary: you can read every change, rebuild it yourself, and check that what you run matches what's published. It is an INDEPENDENT project — not affiliated with, endorsed by, or derived from any commercial product, and it ships no third-party proprietary code. ## Why it exists - Privacy is the default, not an add-on. De-Googled base, engine-level signal control, no built-in tracking or update beacons. - Trust through transparency. The "stealth browser" space is full of closed binaries that ask for blind faith. Clearcote's stance: don't trust us — verify us. - Built for builders. Clean repo layout, scriptable builds, and an AGENTS.md so humans AND automated tooling can navigate and contribute. - It's just Chromium. Native Playwright/Puppeteer support and the ecosystem you know. ## Principles | Principle | What it means | |---|---| | Open by default | 100% open source. Every patch is human-readable. No proprietary blobs in the tree. | | Engine-level, not script injection | Controls are compiled into the binary, not bolted on via brittle, self-revealing injected JavaScript. | | Coherent identity | Signals are controlled together so they stay internally consistent and stable per site. | | Reproducible & verifiable | Pinned upstream revision, deterministic patch set, checksummed and signed artifacts. | | Responsible by design | Built for privacy, testing and lawful automation. You are responsible for how you use it. | --- ## Architecture / how it works A thin, auditable stack — each layer is open and replaceable: ``` Chromium (Google, BSD-3) | ungoogled-chromium -> removes Google services, telemetry, integration | Clearcote patches -> engine-level identity & privacy controls | reproducible build -> checksummed, signed, rebuildable by anyone | Clearcote Browser + Playwright / Puppeteer drop-in ``` ### Engine-level, not script injection Most "stealth" tooling injects JavaScript to overwrite `navigator` properties at runtime. That is brittle and self-revealing — the overrides themselves become a fingerprint (wrong prototype chains, getter timing, missing native-code stringification). Clearcote instead modifies the C++ engine, so the values a page reads come from the same code paths Chromium always uses; there is no injected layer to detect, and it covers APIs JavaScript can't cleanly intercept. ### Coherent, per-site identity (farbling) Randomizing each signal independently produces an identity that doesn't add up — a dead giveaway. Clearcote derives all signals from a single seed combined with the site's registrable domain (eTLD+1), so values are: - Internally consistent — platform, GPU, timezone and locale agree with each other. - Stable per site — the same site sees the same identity across a session. - Decorrelated across sites — different domains see different values, so you aren't linkable across the web. This per-eTLD+1 model is inspired by Brave's farbling approach. ### Coherent persona model (one seed -> one believable machine) Clearcote goes a step beyond per-signal noise: a single `--fingerprint` seed derives one COHERENT Windows persona — a single believable machine whose properties agree with each other. From the seed it draws a hardware tier (CPU cores and RAM that ship together — never 20 cores with 4 GB), a matching screen resolution / available work area / colour depth / device pixel ratio, a coherent GPU (WebGL vendor + renderer + parameter limits), and a real Chrome version (used for the User-Agent and UA-CH). Hardware-class properties are CONSTANT for the session — a real machine doesn't change its core count or screen size between sites — while the noisy, per-render surfaces (canvas, WebGL pixels, audio) stay per-site farbled so you remain decorrelated across domains. Why this matters: the dominant modern bot signal isn't any single value, it's INTERNAL CONTRADICTION — a machine that claims one OS but renders like another, or pairs a 20-core CPU with 4 GB of RAM. Deriving every signal from one persona table guarantees they tell the same story. The persona is Windows-only by design: Clearcote ships a Windows binary, so every persona is a believable Windows PC. It is driven by the same `--fingerprint` seed you already pass — no new flags — so the same seed always yields the same machine. ### What it controls Canvas 2D · WebGL renderer + parameters · AudioContext · Fonts · Timezone · User-Agent + UA-CH · hardwareConcurrency · deviceMemory · Screen geometry · Client rects · navigator.webdriver · Headless hints · Closed shadow roots — all drawn from one coherent persona. ### Build target Windows x64, cross-compiled from Linux against Chromium 149 with clang-cl / lld-link. --- ## Installation (Windows x64) 1) Download from GitHub Releases (https://github.com/clearcotelabs/clearcote-browser/releases). Each release ships: - `clearcote--windows-x64.zip` — the build (Chromium + runtime + VC++ DLLs) - `...zip.sha256` and `SHA256SUMS.txt` — checksums - `...asc` + `clearcote-signing-key.asc` — GPG detached signatures and the public key 2) Verify (recommended) — see "Verification" below. Don't trust, verify. 3) Unzip & place the binary (the archive is self-contained; VC++ 2015–2022 runtime DLLs are bundled, so it runs on a clean Windows 10/11 box): ```powershell Expand-Archive clearcote-149.0.7827.114-windows-x64.zip -DestinationPath C:\clearcote # you now have: # C:\clearcote\chrome.exe # C:\clearcote\chrome.dll + runtime, locales, ICU, ANGLE, VC++ DLLs ``` 4) Smoke test: ```powershell C:\clearcote\chrome.exe --fingerprint=seed-123 --fingerprint-platform=windows ^ https://abrahamjuliot.github.io/creepjs/ ``` Same `--fingerprint` seed => the same identity every launch; a new seed => a fresh one. Requirements: Windows 10/11 x64; no separate VC++ redistributable needed; for automation, your existing Playwright or Puppeteer install (Clearcote replaces the browser, not the driver). --- ## Use it with Playwright / Puppeteer (drop-in, works today) Point your launcher at the Clearcote binary with `executablePath` (Node) / `executable_path` (Python) and pass identity options as `args`. Playwright (Python): ```python from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch( executable_path=r"C:\clearcote\chrome.exe", headless=False, args=[ "--fingerprint=seed-123", "--fingerprint-platform=windows", "--timezone=America/New_York", ], ) page = browser.new_page() page.goto("https://abrahamjuliot.github.io/creepjs/") browser.close() ``` Playwright (Node): ```javascript import { chromium } from "playwright"; const browser = await chromium.launch({ executablePath: "C:\\clearcote\\chrome.exe", headless: false, args: ["--fingerprint=seed-123", "--fingerprint-platform=windows", "--timezone=America/New_York"], }); const page = await browser.newPage(); await page.goto("https://abrahamjuliot.github.io/creepjs/"); await browser.close(); ``` Puppeteer (Node): ```javascript import puppeteer from "puppeteer-core"; const browser = await puppeteer.launch({ executablePath: "C:\\clearcote\\chrome.exe", headless: false, args: ["--fingerprint=seed-123", "--fingerprint-platform=windows"], }); const page = await browser.newPage(); await page.goto("https://abrahamjuliot.github.io/creepjs/"); await browser.close(); ``` Profiles & persistence — reuse the same `--fingerprint` seed and a user-data dir: ```python browser = p.chromium.launch_persistent_context( user_data_dir=r"C:\clearcote\profiles\acme", executable_path=r"C:\clearcote\chrome.exe", headless=False, args=["--fingerprint=acme-tenant-7"], ) ``` ### SDK (shipped) — `clearcote` on npm + PyPI A thin `clearcote` package wraps the above: identity options become named arguments, the verified binary is auto-downloaded + SHA-256-checked on first use (cached), and `launch()` returns a standard Playwright Browser. Install `pip install clearcote` / `npm install clearcote` (no `playwright install` needed — Clearcote ships its own binary). ```python from clearcote import launch browser = launch( fingerprint="seed-123", platform="windows", timezone="America/New_York", proxy={"server": "http://host:8080", "username": "u", "password": "p"}, geoip=True, # auto-match timezone / language / geo / WebRTC-IP to the proxy's exit IP humanize=True, # human-like (bezier, trusted) mouse moves + clicks + scroll show_cursor=True, # draw a cursor dot so you can watch the motion ) page = browser.new_page(); page.goto("https://example.com"); browser.close() ``` ```javascript import { launch } from "clearcote"; const browser = await launch({ fingerprint: "seed-123", platform: "windows", geoip: true, humanize: true }); const page = await browser.newPage(); await page.goto("https://example.com"); await browser.close(); ``` SDK-level options (on top of every flag below + all standard Playwright launch options): - `geoip` — resolve the proxy's exit IP and auto-fill any unset timezone / Accept-Language / location / WebRTC-IP so the whole identity matches the proxy's region (offline MaxMind lookup). - `acceptLanguage` / `accept_language` — sets navigator.languages AND the Accept-Language header coherently (Chromium `--accept-lang`). - `webrtcIp` / `webrtc_ip` — WebRTC reports this IP; the engine FABRICATES the server-reflexive candidate at it and sends NO real STUN, so the real IP never leaks (not merely relabeled). - `humanize` — route clicks/moves/scroll through the engine's `humanizedClick`: a real, trusted (`isTrusted===true`) cubic-bezier mouse path; `navigator.webdriver` stays false. - `showCursor` / `show_cursor` — overlay a red cursor dot that tracks the humanized motion. Migration is a one-line import change — same objects, same methods. --- ## Fingerprint flags (full reference) Everything keys off `--fingerprint=`. The seed (an integer or any string) deterministically derives canvas, WebGL, audio, font and client-rect noise. - Same seed => same identity across launches (a returning visitor). - New seed => a fresh, plausible identity. - Signals are derived per site (farbling), so the same seed is decorrelated across domains rather than globally linkable. | Flag | Value | Description | |---|---|---| | `--fingerprint` | `` | Master seed (int or string). Drives canvas, WebGL, audio, fonts and client-rect noise. Same seed => same identity. | | `--fingerprint-platform` | `windows\|linux\|macos` | Spoof the OS reported to the page (navigator.platform + UA-CH). | | `--fingerprint-platform-version` | `` | Platform version reported via User-Agent Client Hints. | | `--fingerprint-brand` | `Chrome\|Edge\|Opera\|Vivaldi` | Browser brand presented in the UA and UA-CH brand list. | | `--fingerprint-brand-version` | `` | Brand version string. | | `--fingerprint-gpu-vendor` | `` | Override the WebGL UNMASKED_VENDOR string. | | `--fingerprint-gpu-renderer` | `` | Override the WebGL UNMASKED_RENDERER string. | | `--fingerprint-hardware-concurrency` | `` | Value reported by navigator.hardwareConcurrency. | | `--fingerprint-location` | `` | Geolocation coordinates returned to the page. | | `--timezone` | `` | IANA timezone, e.g. America/New_York. Sets the JS timezone coherently. | | `--accept-lang` | `` | navigator.languages AND the Accept-Language request header, e.g. `en-US,en`. Keep coherent with timezone/geo. | | `--webrtc-ip` | `` | WebRTC reports this IP (your proxy egress). The engine fabricates the srflx candidate at it and sends no real STUN, so the real IP never leaks — not a relabel. | | `--fingerprinting-canvas-image-data-noise` | — | Enable canvas image-data noise. | | `--disable-gpu-fingerprint` | — | Disable the GPU/WebGL fingerprint spoof for this session. | Examples — a full, coherent Windows identity: ```bash --fingerprint=acme-tenant-7 \ --fingerprint-platform=windows \ --fingerprint-brand=Chrome \ --timezone=America/New_York \ --fingerprint-hardware-concurrency=8 ``` A macOS identity with custom GPU strings: ```bash --fingerprint=42 \ --fingerprint-platform=macos \ --fingerprint-gpu-vendor="Apple" \ --fingerprint-gpu-renderer="Apple M2" ``` Pin a location together with its timezone so geolocation and clock agree: ```bash --fingerprint=nyc-1 \ --timezone=America/New_York \ --fingerprint-location=40.7128,-74.0060 ``` Coherence matters more than any single value: keep platform, timezone, locale and GPU plausible TOGETHER. --- ## Verification Every release is checksummed and GPG-signed against a single, out-of-band PINNED key. Verification = import the key, CONFIRM its fingerprint equals the pinned value, then check the signature. Never trust whatever key is merely attached to a release. Pinned signing key (ed25519): CA96 F185 F96A 693A EDB3 AC1F CB00 D851 B7A8 6B0F ```bash # 1. inspect the public key and CONFIRM the fingerprint matches the pinned value gpg --with-fingerprint --show-keys clearcote-signing-key.asc # 2. import it gpg --import clearcote-signing-key.asc # 3. verify the signed checksum file (expect: Good signature) gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt # 4. verify the archive's checksum (expect: OK) sha256sum -c clearcote-149.0.7827.114-windows-x64.zip.sha256 # 5. (optional) confirm the inner binary matches SHA256SUMS.txt unzip -p clearcote-149.0.7827.114-windows-x64.zip chrome.exe | sha256sum ``` A "this key is not certified with a trusted signature" warning on step 3 is expected — the proof is the FINGERPRINT MATCH plus the "Good signature", not a trust marker. Windows PowerShell hash-only check: ```powershell (Get-FileHash .\clearcote-149.0.7827.114-windows-x64.zip -Algorithm SHA256).Hash.ToLower() # must equal the zip line in SHA256SUMS.txt ``` Reproducibility: pinned upstream revision, a readable patch set, and a public `config/args.gn`. Chromium cross-builds are not yet bit-for-bit deterministic, so the guarantee today is "every change is an auditable patch and the config is public"; full hash-match attestation is on the roadmap. Canonical steps: docs/VERIFY.md. --- ## Build from source A Clearcote build is upstream Chromium plus a transparent, ordered patch set: 1. Fetch ungoogled-chromium at the pinned revision (Chromium 149). 2. Prune the source, then apply the ungoogled patch set (de-Googling). 3. Apply the Clearcote patches (engine-level identity controls). 4. Drop in the public `config/args.gn`. 5. `gn gen out/Default` then `ninja -C out/Default chrome`. ```bash git clone https://github.com/clearcotelabs/clearcote-browser cd clearcote-browser ./build.sh # or run scripts/00..05 individually ninja -C out/Default chrome ``` Windows is cross-built on Linux with clang-cl / lld-link (Windows SDK + CRT staging, toolchain shims) — every step and gotcha is documented to be reproducible. Canonical guides in the repo: - docs/BUILDING.md — full build-from-source guide - docs/PATCHES.md — what each patch in the set does - docs/RESEARCH-DOSSIER.md — deep cross-build notes - config/args.gn — the public build configuration Because the patch set and config are public and pinned, a build you produce should match the published artifact's behavior — and you can diff the patches against pristine upstream to see every single change. --- ## Roadmap Built in the open; dates omitted — milestones ship when verifiable. ([x] = done) Phase 0 — Foundations (in progress) - [x] Project scope, principles, and architecture - [x] De-Googled base via ungoogled-chromium, pinned to an exact upstream revision - [x] Reproducible source-prep pipeline (fetch -> prune -> patch -> verify) - [ ] Clean, automated build from source on a commodity machine - [ ] Published patch set: every change human-readable and individually documented Phase 1 — First public build (next) - [ ] Windows x64 build as the first target - [ ] Checksummed release artifacts (SHA-256) on GitHub Releases - [ ] Reproducible build instructions a third party can follow to get a matching binary - [ ] One-command source bootstrap for contributors Phase 2 — Coherent identity controls - [ ] Per-profile, deterministic identity seed (stable when you want, fresh when you don't) - [ ] Engine-level controls for canvas, WebGL, audio, fonts, locale/timezone, navigator & hardware reporting, and WebRTC - [ ] Per-site coherence (farbling-style): same site stable, different sites uncorrelated - [ ] Sensible, documented, privacy-respecting defaults Phase 3 — Automation SDK - [ ] Python + Node SDKs, Playwright-first, Puppeteer supported - [ ] launch() returns a standard Playwright object — one-line migration - [ ] Auto-download + local cache of the verified binary - [ ] Recipes: persistent profiles, proxy configuration, headless on servers Phase 4 — Trust & supply-chain - [ ] Build provenance / attestation (e.g. Sigstore-style) for every release - [ ] Signed tags and a documented verification workflow - [ ] CI that builds, checksums, and publishes in the open - [ ] A public "verify this release" guide anyone can run in minutes Phase 5 — Beyond - [ ] Additional platforms (Linux, macOS) - [ ] A self-hostable profile manager for organizing identities and proxies - [ ] Integrations with common automation/agent frameworks - [ ] Hardening informed by open fingerprinting research --- ## FAQ Q: Is Clearcote legal to use? A: It's a privacy/automation tool for lawful purposes — protecting your own privacy, web/QA testing, research, accessibility, and automation you're authorized to run. You're responsible for how you use it; respect site terms and applicable laws. Q: Does it bypass a specific anti-bot service? A: It controls fingerprint SIGNALS so a session presents one coherent, plausible identity. It is not marketed against, and does not target, any specific detection product, and is not a guarantee of evading any system. Validate behavior yourself. Q: How is this different from JS-based stealth plugins? A: Those overwrite navigator properties at runtime with injected JavaScript — brittle and self-revealing. Clearcote changes the C++ engine, so values come from Chromium's own code paths; there's no injected layer to detect. Q: Is it undetectable? A: No tool is. Engine-level, coherent controls remove many common tells, but detection is an evolving space. Always validate against CreepJS, BrowserScan and Pixelscan for your use case. Q: Does it phone home or auto-update? A: No. It's built on ungoogled-chromium — Google services, telemetry and update beacons are removed. Q: Which platforms are supported? A: Windows x64 today. Additional platforms are on the roadmap. Q: Can I keep my existing Playwright/Puppeteer code? A: Yes — it's a drop-in browser. Point executablePath at the Clearcote binary. Q: How do I run multiple distinct identities? A: Use a different --fingerprint seed per identity (e.g. derived from a tenant/account id) and a separate user-data dir per profile for cookies/storage. Q: Is it really open source? A: Yes — BSD-3-Clause. Every patch is human-readable and the build is reproducible from source. Don't trust us, verify us. --- ## For agents & LLMs — integration recipe Machine-readable summary: https://clearcotelabs.com/llms.txt Repo conventions for contributors: AGENTS.md in the repository. ```json { "name": "Clearcote", "kind": "open-source anti-detect Chromium browser", "base": "ungoogled-chromium 149", "identity_model": "engine-level, coherent, per-site (farbling-style)", "automation": "drop-in for Playwright & Puppeteer (executablePath)", "platforms": ["windows-x64"], "license": "BSD-3-Clause", "repo": "https://github.com/clearcotelabs/clearcote-browser", "verify": "GPG-signed + sha256, pinned key", "control_via": "chromium command-line switches (args)" } ``` Minimal integration: 1. Resolve the binary path (e.g. C:\clearcote\chrome.exe). 2. Launch via your existing driver with executablePath. 3. Pass a deterministic --fingerprint= derived from the identity you're acting as. 4. Keep platform / timezone / locale coherent (see the flag reference). ```python from playwright.sync_api import sync_playwright SEED = "agent:" + task_id # stable, reproducible identity per task with sync_playwright() as p: browser = p.chromium.launch( executable_path=r"C:\clearcote\chrome.exe", args=[f"--fingerprint={SEED}", "--fingerprint-platform=windows"], ) page = browser.new_page() page.goto("https://example.com") ``` Tip: derive the seed from a stable id (tenant, account, task) so the same actor always gets the same browser fingerprint — reproducible and debuggable. --- ## Inspiration & credits - Chromium (BSD-3-Clause) — the engine. https://www.chromium.org/ - ungoogled-chromium (BSD-3-Clause) — the de-Googled base and patch tooling. https://github.com/ungoogled-software/ungoogled-chromium - fingerprint-chromium by adryfish (BSD-3-Clause) — pioneering engine-level fingerprint controls. https://github.com/adryfish/fingerprint-chromium - Brave — the per-site deterministic "farbling" model. https://brave.com/privacy-updates/3-fingerprint-randomization/ - Camoufox — a sibling open anti-detect browser (Firefox-based). https://github.com/daijro/camoufox ## Responsible use Clearcote is a privacy and automation tool intended for lawful purposes — protecting your own privacy, web/QA testing, research, accessibility, and automation you are authorized to run. You are responsible for how you use it. Respect website terms of service, applicable laws, and others' rights. Provided "as is", without warranty. --- Docs index: https://clearcotelabs.com/docs - Introduction: https://clearcotelabs.com/docs - Installation: https://clearcotelabs.com/docs/installation - Playwright/Puppeteer: https://clearcotelabs.com/docs/playwright - Fingerprint flags: https://clearcotelabs.com/docs/fingerprint - Architecture: https://clearcotelabs.com/docs/architecture - Verification: https://clearcotelabs.com/docs/verification - Build from source: https://clearcotelabs.com/docs/building - For agents & LLMs: https://clearcotelabs.com/docs/agents