Keeping Clearcote up to date

Without a licence key, each SDK version is pinned to one SHA-256-verified open build, and updating it is a normal package bump. With a key, the SDK fetches the current licensed build on every launch — no bump needed.

Which builds are available

The Chromium majors we currently ship or are working on, and when each tier gets them:

SDK users (recommended)

Bump the package the way you update any dependency:

npm i clearcote@latest          # Node
pip install -U clearcote        # Python
dotnet add package Clearcote    # .NET (adds or updates to the newest version)

On the next launch() the SDK notices the build it needs isn't cached, downloads it — the open build from GitHub Releases, the licensed build from clearcotelabs.com — and verifies the SHA-256 before use. Nothing runs unverified. Builds are cached per build in your user cache directory — %LOCALAPPDATA%\clearcote\Cache on Windows, ~/.cache/clearcote on Linux (set CLEARCOTE_CACHE to move it) — so each is a one-time download. Old builds are kept until you run clearcote clear-cache.

Several programs, one cache

Programs that share the cache take turns installing a build (SDK 0.41.0+, Python, Node and .NET alike): the first one downloads it, the others wait and then use it, and a build another program is running is never replaced under it. A program that waits gives up after 30 minutes with a message naming the process that holds the install (the lock is the .install-lock file in that build's cache folder; the message says when it is safe to delete it). A lock left behind by a crashed program is taken over by itself.

A cached build whose files were damaged or removed (an antivirus quarantine, a deleted folder) is repaired on the next launch with one download. If its files are still in use, the launch stops at once and asks you to close every program that uses that browser, then try again. The lock needs every process sharing the cache to run SDK 0.41.0 or newer; older releases do not wait for it.

Windows: some setups cannot start a downloaded build where it is, for example a program running inside a packaged (MSIX) app, whose writes to %LOCALAPPDATA% Windows redirects (the launch fails with spawn UNKNOWN or "the side-by-side configuration is incorrect"). There the SDK makes one copy of the build in ~/.clearcote/recovered, and every later launch from Python, Node or .NET uses it, so nothing is left in the temporary folder and repeat launches start in seconds (Python and Node from 0.40.1, .NET from 0.41.0). clearcote clear-cache removes those copies too; the .NET SDK has no command line, so call WinLaunch.ClearRecovered() there.

Update the open build without upgrading the SDK

Without a key, opt into auto-update to take the newest open build on GitHub instead of the SDK's pin. It is verified against that release's SHA256SUMS.txt (and against the signing key when gpg is installed); if GitHub is unreachable it falls back to the pinned build. From a shell, clearcote update does the same. With a key it changes nothing — you already get the current licensed build.

import { launch } from "clearcote";
await launch({ autoUpdate: true });   // or set env CLEARCOTE_AUTO_UPDATE=1

The browser itself never phones home or updates itself. Without a key, the browser changes only when you bump the SDK or turn on autoUpdate. With a key, the SDK picks up each new licensed build on the next launch; Pro can hold a build with version.

Choosing a build

Pass version (or set CLEARCOTE_BROWSER_VERSION): "latest", a major like "154", an exact "154.0.8037.57", or a licensed revision "r35" / "154.0.8037.57-r35". A version or major is checked against the published catalog, and a revision against the licence server, before anything downloads. releaseChannel: "preview" (release_channel in Python, or CLEARCOTE_RELEASE_CHANNEL=preview) takes a preview build when one exists. On the licensed build, older builds, pinning and the preview channel are Pro features — free keys always get the latest.

clearcote install --version 154        # fetch + verify a build ahead of time
clearcote install --channel preview     # the newest preview build (Pro)
clearcote info                          # what's installed and cached, and your key
clearcote clear-cache                   # delete cached builds

Direct / Docker users

• Direct binary (open build only — the licensed build runs through the SDK, clearcote serve or the Docker image): download the new archive from the Releases page, verify the checksum + signature (see Verification), and point executable_path / executablePath (or CLEARCOTE_BINARY) at the new chrome.
• Docker: docker pull teamflatearth/clearcote for the latest image, then recreate your container. Free keys need an image built from SDK 0.30.0 or newer. With a key, mount -v clearcote-cache:/opt/xdg-cache so the licensed build downloads once rather than into every new container. See Deployment.

The licensed build — always current, and first

The licensed build tracks the latest Chromium and the newest patches, so you get updates without manual rebuilds. Set CLEARCOTE_LICENSE_KEY, pass licenseKey, or run clearcote login (Python/Node; npx clearcote login for a local npm install) — it checks the key and saves it to ~/.clearcote/license.key, which every SDK, .NET included, reads. There are two ways to get a key:

• Free with GitHub — one browser at a time, at no cost. Sign in with a GitHub account that is at least 30 days old, open Licenses in your dashboard, click Connect GitHub and get it free, then Claim my free key (one per GitHub account). The key lasts 30 days; renew it free from the same page before it runs out.
• Pro — the same build with up to 250 browsers at once, older builds, version pinning and the preview channel, plus email support from the owner.

New majors reach the licensed build first. When a new Chromium major is built, it's available on Free with GitHub and Pro immediately; the open build gets that major later — the target is about 2 months after release (it is on Chromium 150 today). The open build is always fully open and reproducible; the licensed build gets the newest one sooner.

How licensed browsers are counted

Every browser started with a key takes a slot from the licence server and gives it back when it closes. Your dashboard shows how many are in use, and clearcote info prints the same count.

• Free with GitHub counts every browser. One slot, so a second browser — in the same program, in another program or on another machine — is refused with The free tier runs one browser at a time, and one is already running until the first one closes. A browser that crashed without closing frees its slot within 6 minutes.
• Pro counts machines, and covers up to 250 browsers at once. All browsers on one machine share that machine's slot. Subscriptions started before 26 September 2026 keep their previous uncapped terms; if you need more than 250, ask and we will raise it.
• Free keys need SDK 0.30.0 or newer (Python, Node and .NET), because counting every browser needs the SDK to report each launch and to keep the licence current while that browser runs. An older SDK gets SDK_UPGRADE_REQUIRED with the upgrade command, and an older SDK that reaches the engine anyway is refused there. Pro keys work with older SDKs as before.
• A free browser stops when its slot goes away. The check is continuous, not only at start-up: if the key is revoked, the slot is checked in elsewhere, or the licence goes over its limit, a free browser that is already open shuts down within about 2 to 3 minutes. Short network drops (a missed heartbeat or two) are absorbed; an outage of more than about 2 to 3 minutes stops a free browser the same way.
• Free always runs the latest build. Asking for an older licensed build or the preview channel returns FREE_LATEST_ONLY; pinning a build is a Pro feature.
• Downloads on a free key: up to 10 different builds per 24 hours. The same build counts once however often you start it.

pip install -U clearcote          # Python 0.30.0+
npm i clearcote@latest            # Node 0.30.0+
dotnet add package Clearcote      # .NET 0.30.0+

What changes when you upgrade

Most SDK releases change nothing you have to act on. These ones change what an existing setup does; every release is listed under Releases in your dashboard.

• 0.41.1, humanized input: with humanize, scrolling moves in whole mouse-wheel notches, the way a real wheel does: 100 px a notch on a Windows identity, 120 on Linux and 40 on macOS. A requested distance is rounded to the nearest notch (at least one), so mouse.wheel(0, 800) scrolls 800 px on Windows and 840 on Linux. Typing now sometimes presses the next key before releasing the previous one on fast pairs. In .NET, a humanizer seeded with a number now moves with the same motor identity as in Python and Node; before, every nonzero number seed shared one. See Humanized input.
• 0.41.0 on the licensed build from r32: the persona reaches the browser through its environment instead of its command line, so a tool that read the seed from the process list no longer finds it (persona_env=False keeps the old way). The contexts a local launch creates no longer emulate a light colour scheme, so a dark persona reports dark everywhere (pass color_scheme to pin one). A headless Linux launch with a persona gets a screen the size the persona claims. See Launch options.
• 0.41.0, .NET on Linux: launches now use the browser's bundled fonts, as Python and Node always have, instead of the host's. A Windows persona there measures differently, now like the other two SDKs. See your own fonts on Linux.
• 0.41.0, a Linux persona on a Windows computer: the SDK warns once per process. Windows runs the GPU through Direct3D, which caps the WebGL and WebGPU limits, and a persona can lower a limit but never raise one past the driver's, so a Linux persona there reports limits no Linux machine has. Claim Windows on Windows, or run Linux personas on Linux or in Docker. quiet or CLEARCOTE_NO_WARN silence it.
• Docker image sdk-0.41.0: Chrome can run with its sandbox, if you start the container with the image's seccomp profile; without it the container runs as before. Script fonts are built in. See Deployment.
• 0.40.0: on macOS, launch() runs the Clearcote Docker image (Docker Desktop needed; docker=False turns it off). See macOS.

After upgrading, re-verify

A new build can shift a signal. Re-run your fingerprint checks (e.g. CreepJS) and, if you use an imported profile, confirm it still loads coherently — see Verification. The current open build is v0.1.0-pre.23 (Chromium 150.0.7871.114); the current licensed build is 154.0.8037.57-r35. The roadmap tracks what's next.