For agents & LLMs

Clearcote is laid out so automated tooling can navigate, integrate and contribute as easily as a human. Setting Clearcote up for someone? Follow the setup runbook.

Setup runbook for coding agents

If you are an AI coding agent (Claude Code, Codex, Cursor, Windsurf, Cline and the like) asked to set up Clearcote for someone, work through the steps below in order: installed, licence set, running, verified. Each step has a check, and a step is done only when its check passes. Keep your progress in a file, so that a new session, or a user who comes back tomorrow, resumes at the first step that is not done instead of starting over. The same runbook is one markdown file at /setup.md, the address the homepage gives you to paste into an agent; it is the canonical copy, and this section follows it heading for heading.

Rules

• Run every command yourself and read its output. If a step fails, stop and report. Tell the user which step failed, the command you ran and the exact error line, then the fix from the table below. Don't work around a failed check (skipping verification, pinning an older build, switching builds) without asking.
• Install only from the official sources: the clearcote package on PyPI, npm or NuGet, clearcote-mcp on PyPI and npm, the teamflatearth/clearcote Docker image, and the releases of clearcotelabs/clearcote-browser. The SDK downloads the browser itself and checks its SHA-256: never fetch a browser build from anywhere else, and never turn that check off.
• Never ask the user to paste a licence key or API key into the chat, and never print, log or commit one. If one is pasted anyway, don't repeat it, don't write it into any file you create, and suggest rotating it on the Licenses page.
• When a link has expired or is dead, don't look for a copy. The download links the SDK uses are short-lived and it requests a fresh one on every run, so rerun the command rather than reusing a URL. For any other link (a sign-in, a device code, a dashboard page, a link the user forwarded), go back to where it came from, or ask the user for a new one. Never fall back to a mirror, a cached copy or an unofficial package.
• Install into the user's project (its virtualenv, package.json or .csproj), not globally, unless the user asks otherwise. Ask before you edit config outside the project (an MCP client's config, for example) and before you start anything that costs money (hosted browsers are billed per GB).
• Done means the exact browser version is confirmed, not that a package installed.

Keep a progress file

Write clearcote-setup.json in the project root (it holds no secrets) and update it after every check. route is python, node, dotnet, mcp or docker; build is open (no key) or licensed (Free with GitHub or Pro); blocked records what you are waiting for.

{
  "route": "python",
  "build": "licensed",
  "steps": {
    "installed":   { "done": true,  "checked": "2026-10-06T10:12:00Z", "evidence": "clearcote SDK 0.67.1" },
    "licence_set": { "done": false },
    "running":     { "done": false },
    "verified":    { "done": false, "browser_version": null }
  },
  "blocked": { "step": "licence_set", "waiting_for": "user approves the device sign-in" }
}

At the start of a session, read the file and continue from the first step that is not done. Rerun the check of any earlier step you rely on, because a key can expire and a cache can be cleared between sessions.

Step 0: choose the route and the build

Ask the user once, and record the answers.

• The route. For their own code: the SDK in the project's language, Python 3.8+, Node 20+ or .NET 8 (if there is no project yet, suggest Python). For you, the agent, to browse with: the MCP server (Python 3.10+). As a CDP endpoint for an existing framework: the Docker image.
• The build. The open build needs no key and no sign-up: Chromium 151, open source (BSD-3), good enough to start. The latest build is Chromium 156, with a licence key: free with GitHub for one browser at a time, or Pro for up to 250 browsers at once.

The browser runs on Windows x64 and Linux x64, and the Docker image is x64 too. On an Apple Silicon Mac the licensed build runs natively as a preview (SDK 0.51.1+, with a licence key); on an Intel Mac or without a key, launch() runs the Docker image through Docker Desktop. On any other ARM machine, stop and say so; hosted browsers are the option that needs no local browser.

Step 1: installed

pip install -U clearcote                  # Python, inside the project's virtualenv
npm install clearcote                     # Node
dotnet add package Clearcote              # .NET (see below for the checks)
pip install -U clearcote clearcote-mcp    # MCP server: Python 3.10+, no mcp pin needed
docker pull teamflatearth/clearcote       # Docker

The check: clearcote version (Node: npx clearcote version) prints 0.67.1 or newer. For Docker, docker image ls teamflatearth/clearcote lists the image.

.NET has no clearcote command of its own. Check that dotnet list package lists Clearcote, then run every clearcote command in steps 1 to 3 as npx -y clearcote <command> (Node 20+) or pipx run clearcote <command> (Python 3.8+). That adds nothing to the project, and the command uses the same browser cache and licence file (~/.clearcote/license.key) as the .NET SDK. If the machine has neither Node nor Python, ask the user to install one: without the command the browser version cannot be confirmed, so the setup cannot be verified.

Step 2: licence set

For the open build, mark this step done with the evidence open build, no key. For the latest build, the key goes to the user's machine without passing through you:

• If clearcote --help lists clearcote login --device, run clearcote login --device (Node: npx clearcote login --device). It prints a link and a short code. The user opens the link in their own browser, signs in and approves (a free key needs a GitHub account at least 30 days old, a card check that is never charged, or a company Google account), and the SDK saves the key to ~/.clearcote/license.key without showing it.
• Otherwise the user claims a key on the Licenses page and runs clearcote login (Node: npx clearcote login) in their own terminal, pasting the key there: it shows on their screen, never in the chat. Give them those steps and wait until they say it is done. They can instead set CLEARCOTE_LICENSE_KEY themselves, in their shell profile, CI secrets, the env block of their MCP client config, or their Docker environment (docker run -e CLEARCOTE_LICENSE_KEY then passes it in without the value appearing in the command).

Never run clearcote login <key> yourself: the key would land in your transcript and the shell history. Don't open ~/.clearcote/license.key either. The check: clearcote info --quick shows the Licence line as a masked key from file or from env, which is all you need to see. none (free build) means no key was found. A key set only in an MCP client's config or a container is invisible to your shell; check that the variable name is there without printing its value.

Step 3: running

clearcote install    # downloads and verifies the build the key allows
clearcote info       # starts the browser once, headless

(Node: npx clearcote install and npx clearcote info.) The check: clearcote info prints Launch test ok with the browser version (with --json: launch.ok is true, launch.version holds the version and binary.tag the build). On a Free key this uses the one browser seat for a moment, so close any other Clearcote browser first. Then, by route:

• SDK: run a first script, clearcote_hello.py or clearcote_hello.mjs. The check: it prints Example Domain and a Chrome user agent, then exits. On .NET, use the C# tab of Playwright & Puppeteer. The fingerprint seed is the identity: the same seed gives the same device every time, so use one seed per account.
• MCP server: register the command clearcote-mcp with the client (ask first; give the full path if it is in a virtualenv), as on MCP server. Restart the client and call its navigate tool on https://example.com; it returns the final URL and the page title.
• Docker: start a container and read its log and endpoint, as below.

import clearcote

browser = clearcote.launch(fingerprint="first-run")
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
print(page.evaluate("navigator.userAgent"))
browser.close()

Step 4: verified

Compare what step 3 printed with the build the user should have. In Docker, the build tag is part of the engine path in the log line.

A Pro plan that pins an older build reports that build instead. If it is not the build the user chose, stop and tell them. When the version matches, set verified to done with the version, and tell the user: the route, the SDK version, which build runs and its exact browser version, where the first script is and how to run it, where the key is kept (file or environment variable, never the key itself), and the docs.

When a step fails

Optional, only if the user wants it

• A proxy. Pass a Playwright proxy and geoip=True, so the timezone and language follow the proxy's exit IP. See Proxies & geoip.
• A browser for you, the agent, over MCP, if that was not the route: pip install -U clearcote-mcp (Python 3.10+), then register it as in step 3. For the latest build the server finds the key saved in step 2, or the user adds CLEARCOTE_LICENSE_KEY to that server's env themselves.
• No machines to run it on. Hosted browsers start the same browser on Clearcote's servers with one API call. They need an API key and are billed per GB, so ask first.

Machine-readable summary

A concise, plaintext project summary lives at /llms.txt, and the complete documentation flattened into one prompt-ready file is at /llms-full.txt. The repository also ships an AGENTS.md describing layout and conventions for contributors.

{
  "name": "Clearcote",
  "kind": "anti-detect Chromium browser (the open build is open source)",
  "base": "ungoogled-chromium — open build 151 (v0.1.0-pre.25), licensed build 156.0.8078.47-r54",
  "identity_model": "engine-level, coherent seed persona + per-site render noise",
  "automation": "SDK (npm/PyPI/NuGet package clearcote) returning Playwright objects; CDP endpoint for Puppeteer and others",
  "platforms": ["windows-x64", "linux-x64"],
  "license": "BSD-3-Clause (open build + SDKs); the licensed build adds unpublished patches",
  "repo": "https://github.com/clearcotelabs/clearcote-browser",
  "verify": "open build: GPG-signed SHA256SUMS + pinned key; every SDK download: SHA-256",
  "control_via": "SDK options, or chromium command-line switches (args) on the open build"
}

Minimal integration recipe

1. Install the SDK (pip install clearcote / npm i clearcote) — it downloads and verifies the browser.
2. Derive a deterministic fingerprint seed from the identity you're acting as.
3. Behind a proxy, pass geoip=True so timezone, language and WebRTC follow the exit.
4. On the licensed Chromium 156 build (r51 and newer) the SDK also fetches a signed persona for that seed from the Clearcote persona service at every launch (SDK 0.63.0 or newer). Nothing to configure, but the machine must be able to reach it.
5. For frameworks that want a CDP URL (browser-use, Stagehand, Crawl4AI), use serve() or clearcote serve instead.

from clearcote import launch

task_id = "1234"
SEED = "agent:" + task_id          # stable, reproducible identity per task

browser = launch(fingerprint=SEED, geoip=True, humanize=True)
page = browser.new_page()
page.goto("https://example.com")

Driving the open build's binary directly with executablePath also works, but the licensed build only starts through the SDK, and a raw launch loses the SDK's defaults — see Playwright & Puppeteer. For higher-fidelity identity, launch a real captured profile instead of a seed: launch(profile="auto") picks one that suits this machine from the profile library (licensed build), or pass fingerprint_profile="profile.json" (Node: fingerprintProfile). Don't combine a profile with a fingerprint seed.

In-browser AI agent

Clearcote ships an optional, opt-in AI agent that drives a real page autonomously. It perceives the live page, asks a user-configured LLM what to do next, and acts through Chrome's Actor framework with real, trusted input events rather than injected script. It is off by default (inactive unless you supply an agent key or the agent switches) and brings your own key: point it at any OpenAI-compatible / OpenRouter endpoint. Password fields are redacted before anything is sent to the model. Use launch_agent() (a persistent context) — that's the supported path.

From the SDK, launch_agent (Node: launchAgent) returns a persistent BrowserContext, and run_agent_task(page, goal, max_steps=...) (Node: runAgentTask) drives it, returning { success, finalText, steps, stepsJson }. Pass a profile directory as the first argument (userDataDir in Node) to reuse one profile; without it, each call creates a new temporary profile folder that is not removed on close. In .NET (SDK 0.58.0+) the same pair is LaunchAgentAsync / RunAgentTaskAsync.

import os
from clearcote import launch_agent, run_agent_task

# Returns a persistent BrowserContext.
ctx = launch_agent(
    agent_llm_key=os.environ["OPENROUTER_API_KEY"],   # required: the SDK does not read env vars (the CLI does)
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(
    page,
    goal="Find the pricing page and read the cheapest plan",
    model="openai/gpt-4o-mini",                # optional per-task override
    max_steps=20,
)
print(result["success"], result["finalText"], result["steps"])

Agent launch options map directly to binary switches: agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model), and agent_typing / agentTyping. A task runs once the agent has a URL (OpenRouter by default), a key and a model. The agent asks the model for a JSON reply in plain text, so the endpoint doesn't need tool-call support; agent_tool_mode / agentToolMode (--agent-tool-mode, CLI --tool-mode) is accepted but currently has no effect.

agent_typing / agentTyping tunes the agent's keystroke cadence: human (default) types with per-key keydown/keyup timing and keeps long text typing key-by-key, fast is the quick engine cadence, and instant is one-shot. The default avoids the two typing tells — uniform machine-perfect timing, and long text being instant-pasted (which emits zero keystroke events).

clearcote-agent CLI

The same agent is available as a CLI for quick, scriptable runs. Pass a one-shot goal, or drop into an interactive REPL. The model key comes from --key or the $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY environment variables.

# One-shot: run a single goal against a URL, then exit
clearcote-agent --goal "Accept cookies and list the top 3 headlines" --url https://example.com

# Interactive REPL: keep the browser open and issue goals one at a time
clearcote-agent -i

# Use a custom endpoint/model, persistent profile, proxy and step cap
clearcote-agent --llm-url http://localhost:8000/v1 --model local/model \
  --profile ~/.clearcote/agent-profile --proxy http://user:pass@host:8080 \
  --max-steps 12 --goal "Open the dashboard" --url example.com

# Provide the key explicitly (otherwise read from the environment)
clearcote-agent --key sk-or-... --json \
  --goal "Search for 'clearcote' and open the first result" --url https://example.com

CLI options include --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone, and --json. A bare host passed to --url is upgraded to HTTPS.

Where to look

• Fingerprint flags — the full switch reference (also machine-friendly).
• Playwright & Puppeteer — drop-in launch patterns.
• Examples — copy-paste SDK, profile, proxy, canvas bridge, CI and agent recipes.
• In-browser AI agent — opt-in autonomous page driving and the clearcote-agent CLI.
• MCP server — drive Clearcote from Claude Desktop, Cursor or Cline.
• Deployment — clearcote serve: one CDP URL, a separate identity per connection.
• Recommendations — which settings to turn on, and which to leave alone.
• Verification — confirm the binary before running it.
• Source repository — patches, build pipeline, AGENTS.md.

Build deterministic identities: derive the seed from a stable id (tenant, account, task) so the same actor always gets the same browser fingerprint — reproducible and debuggable.