Profiles and persistence

Keep the same identity across runs: reuse a fingerprint seed, keep cookies and storage in a profile directory, or report the values captured from a real Chrome.

Import a real-Chrome profile

Instead of the synthetic, seed-derived persona, you can make Clearcote report the values captured from a real machine. Capture one from a donor Chrome with the collector at tools/fingerprint-collect (open collect.html, click Capture, and it downloads a JSON profile), or bootstrap from the open-source chrome-fingerprints 10k-record dataset with the bundled convert_dataset.py converter. The capture covers navigator, screen geometry, WebGL vendor/renderer + getParameter limits, Web Audio, speech-synthesis voices, fonts, codecs, and CSS @media characteristics.

Pass the profile to the SDK as a file path, object, or JSON string — it handles the gzip + base64 packing for you. Fields present in the profile override what the browser would otherwise report; fields that are absent fall back to the browser's defaults. The SDK also derives Accept-Language from the profile's navigator.languages when you don't set one explicitly. Both builds read imported profiles; on the licensed build they apply in full from 151 r19.

Do not pass a fingerprint seed alongside a profile. The seed engages the farbling layer, which strict scoring reads as canvas tampering, and it buys you nothing the profile is not already supplying. Use one or the other. A profile substitutes reported values only — it never changes what renders your pixels, so two accounts on two different profiles on one machine still produce an identical canvas. If you need per-account render separation, use a per-account seed and no profile.

from clearcote import launch

browser = launch(fingerprint_profile="profile.json", disable_gpu_fingerprint=True, fingerprint_noise=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

Profiles & persistence

Keep a stable identity across runs by reusing the same fingerprint seed, and persist cookies/storage with a user-data dir:

from clearcote import launch_persistent_context

ctx = launch_persistent_context(r"C:\clearcote\profiles\acme", fingerprint="acme-tenant-7", headless=False)
page = ctx.pages[0] if ctx.pages else ctx.new_page()

A profile directory's cookies are encrypted with a key tied to the machine that created it. To copy a profile to another machine with its cookies intact, pass portableProfile: true / portable_profile=True (the key travels with the profile) or encryptionKey / encryption_key (the key is derived from your secret, and nothing sensitive is written to disk). Licensed build, Python & Node.

The SDK also has saved personas: a Profile stores fingerprint options, proxy settings, canvas-bridge settings, and other launch options as JSON under ~/.clearcote/profiles (override with CLEARCOTE_PROFILE_DIR).

from clearcote import Profile, launch, launch_persistent_context

Profile("acct-1", {
    "fingerprint": "acct-1",
    "gpu_vendor": "Google Inc. (Intel)",
    "gpu_renderer": "ANGLE (Intel, Intel(R) UHD Graphics ... D3D11)",
    "canvas_bridge": {"url": "ws://127.0.0.1:8443", "auth": "user:secret"},
}).save()

ctx = launch_persistent_context(r"C:\clearcote\profiles\acct-1", profile="acct-1")
browser = launch(profile="acct-1", headless=False)

Saved profiles are plaintext and may contain credentials such as canvasBridge.auth. Treat profile files as trusted input and don't commit or share them.