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.

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. 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()

3. 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()

4. 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()

5. 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.

6. 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

7. 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()

8. 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.