Skip to content

Examples

Copy-paste recipes for common Clearcote workflows. Start with the smallest one that matches your job, then add options only when you need them.

Recipes are shown for the Python, Node and .NET SDKs (pip install clearcote / npm install clearcote / dotnet add package Clearcote). The .NET SDK covers the core workflows — launch, persistent contexts, serve, proxy and canvas bridge; the higher-level helpers used in a few recipes (humanize, geoip auto-fill, saved profiles, Widevine, the in-browser agent) are Python & Node only for now, with the same engine switches reachable in .NET via Args.

1. Launch a verified browser from the SDK

The SDK downloads and SHA-256-verifies the pinned Clearcote release on first use. It returns standard Playwright objects, so the rest of your automation stays familiar.

from clearcote import launch

browser = launch(fingerprint="demo:user-1", platform="windows", headless=False)
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

2. Serve a stealth CDP endpoint for any framework

serve() runs Clearcote as a standing CDP endpoint and returns a cdp_url. It launches the binary directly — no --enable-automation, so navigator.webdriver stays false— and any Playwright, Puppeteer, browser-use, Crawl4AI, or Stagehand client attaches over CDP with no code change. For an AI agent, point Claude / Cursor / Cline at the clearcote-mcp server (pip install clearcote-mcp or npx -y clearcote-mcp).

from clearcote import serve
from playwright.sync_api import sync_playwright

srv = serve(fingerprint="demo:user-1", platform="windows")   # same persona options as launch()
print(srv.cdp_url)                                           # http://127.0.0.1:<port>

browser = sync_playwright().start().chromium.connect_over_cdp(srv.cdp_url)
page = browser.new_page(); page.goto("https://example.com"); print(page.title())
srv.close()

3. One stable identity per account

Use a deterministic seed and a persistent user-data directory. The seed keeps the browser identity stable; the profile directory keeps cookies, local storage, permissions, and session state.

from clearcote import launch_persistent_context

account_id = "acct_42"

ctx = launch_persistent_context(
    rf"C:\clearcote\profiles\{account_id}",
    fingerprint=f"acct:{account_id}",
    platform="windows",
    timezone="America/New_York",
    accept_language="en-US,en",
    humanize=True,
)
page = ctx.new_page()
page.goto("https://example.com/dashboard")
ctx.close()

4. Match timezone, language, location and WebRTC to a proxy

When geoip is enabled, Clearcote resolves the proxy exit IP and fills unset regional fields from the offline GeoIP database. This avoids hand-matching a timezone to every proxy.

from clearcote import launch

browser = launch(
    fingerprint="proxy:nyc:001",
    platform="windows",
    proxy={"server": "http://host:8080", "username": "user", "password": "pass"},
    geoip=True,
)
page = browser.new_page()
page.goto("https://browserleaks.com/webrtc")
browser.close()

5. Save and reuse a named profile

A saved Profile is useful when you want a named persona that multiple scripts can share. Keep secrets out of source control: profile files are plaintext.

from clearcote import Profile, launch

Profile("support-agent", {
    "fingerprint": "support-agent",
    "platform": "windows",
    "timezone": "America/Chicago",
    "accept_language": "en-US,en",
    "storage_quota": 120000,
}).save()

browser = launch(profile="support-agent", headless=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

6. Use the canvas bridge only where it matters

Bridge mode can be scoped by registrable domain. The example below bridges canvas/WebGL readbacks only on the listed origins and serves local rendering everywhere else.

from clearcote import launch

browser = launch(
    fingerprint="gpu:nvidia:seat-1",
    canvas_bridge={
        "url": "ws://127.0.0.1:8443",
        "auth": "user:secret",
        "mode": "allow",
        "allow": ["example.com", "browserleaks.com"],
        "fallback": "local",
    },
)
page = browser.new_page()
page.goto("https://browserleaks.com/canvas")
browser.close()

Start the bridge host first. See Canvas bridge for the server command, network guidance, and fallback behavior.

7. Play DRM video with Widevine

Clearcote ships the EME plumbing but never Google's proprietary CDM. On a persistent context, widevine fetches the Widevine CDM once from Google's component server, verifies it, seeds it into the profile, and enables it — so requestMediaKeySystemAccess('com.widevine.alpha') resolves and DRM streams play, like a real Chrome.

from clearcote import launch_persistent_context

ctx = launch_persistent_context("C:\\clearcote\\profile-drm", widevine=True)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://example.com")
# requestMediaKeySystemAccess('com.widevine.alpha') now resolves; DRM playback works
ctx.close()

Opt-in by design — the package never distributes Google's CDM; you trigger the one-time fetch (cached under ~/.clearcote/WidevineCdm). Requires a persistent context. Software-secure (L3).

8. Prefetch the browser in CI

Warm the verified browser cache before your test suite starts. This makes failures happen early, before parallel jobs begin.

- name: Install dependencies
  run: |
    python -m pip install clearcote playwright

- name: Prefetch verified Clearcote
  run: |
    python -c "from clearcote import download; print(download())"

- name: Run tests
  run: |
    pytest

9. Run an agent task and keep the trace

The in-browser agent is opt-in. Give it a persistent profile, an OpenAI-compatible endpoint/key, and a bounded step count so the run is reproducible and reviewable.

from clearcote import launch_agent, run_agent_task

ctx = launch_agent(
    profile="agent-demo",
    fingerprint="agent-demo",
    agent_llm_key="sk-or-...",
    agent_model="openai/gpt-4o-mini",
    agent_tool_mode="tools",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(page, "Find the contact page and summarize the email address", max_steps=12)
print(result["success"])
print(result["finalText"])
print(result["stepsJson"])
ctx.close()

10. Raw Playwright when you do not want the SDK

The SDK is the ergonomic path, but Clearcote remains a normal Chromium binary. You can always launch it directly from Playwright or Puppeteer.

javascript
import { chromium } from "playwright";

const browser = await chromium.launch({
  executablePath: "C:\\clearcote\\chrome.exe",
  headless: false,
  args: [
    "--fingerprint=raw-playwright-demo",
    "--fingerprint-platform=windows",
    "--timezone=America/New_York",
    "--accept-lang=en-US,en",
  ],
});

const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
Keep the recipe small first. Add profile import, canvas bridge, agent mode, or manual GPU overrides only when your target workflow actually needs them.