Installation

Installez le SDK et laissez-le récupérer un navigateur vérifié — ou téléchargez et vérifiez un build vous-même.

Clearcote est en développement actif. Des builds sont disponibles pour Windows x64 et Linux x64 — le SDK télécharge celui qui correspond à votre OS. Sur un Mac Apple Silicon, le navigateur tourne nativement (le build sous licence en preview, ou le build ouvert 150 sans clé de licence) ; sur un Mac Intel, launch() exécute l’image Docker de Clearcote pour vous (voir macOS). Sur un hôte Linux minimal, installez les bibliothèques d’exécution du navigateur (libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libpango-1.0-0 …) — clearcote info liste celles qui manquent. Si vous lancez vous-même le binaire en root (le cas typique dans un conteneur), passez --no-sandbox ; le SDK et clearcote serve s’en chargent pour vous.

Installer le SDK (recommandé)

npm i clearcote                # Node 20+
pip install clearcote          # Python 3.8+
dotnet add package Clearcote   # .NET 8

Le premier launch() télécharge le navigateur pour votre OS, vérifie son SHA-256 et le met en cache. Vous n’avez pas à lancer playwright install — chaque SDK apporte son driver Playwright et récupère son propre navigateur. Le build que vous obtenez dépend de la présence d’une clé de licence :

Définir une clé de licence

Le SDK cherche une clé dans cet ordre : l’option de lancement licenseKey / license_key / LicenseKey, puis la variable d’environnement CLEARCOTE_LICENSE_KEY, puis ~/.clearcote/license.key — le fichier qu’écrit clearcote login. Tous les SDK, .NET compris, lisent ce fichier. Obtenez une clé gratuite dans la section « Licenses » de votre tableau de bord.

clearcote login --device                # sign in from a browser on any device; nothing to paste
clearcote login                         # asks for the key; what you paste is not shown
clearcote login cc_lic_...              # for scripts: checks the key, saves it to ~/.clearcote/license.key
export CLEARCOTE_LICENSE_KEY=cc_lic_...  # or per process / per container

Se connecter depuis un autre appareil

clearcote login --device (SDK 0.40.0+, Python et Node ; npx clearcote login --device avec une installation npm locale) enregistre une clé sans que vous ayez à la copier. La commande affiche un lien et un code court. Ouvrez le lien dans un navigateur, sur n’importe quel appareil où vous pouvez vous connecter à clearcotelabs.com, vérifiez que la page affiche le même code que votre terminal, cochez la case qui confirme que ce terminal est bien le vôtre, puis approuvez. La page indique que l’appareil est connecté, et le terminal affiche Signed in as suivi de l’adresse de votre compte (partiellement masquée), de l’emplacement où la clé a été enregistrée, ainsi que de l’offre et de sa date d’expiration. La clé elle-même n’est jamais affichée, ni sur la page ni dans le terminal.

Un code reste valable 10 minutes ; passé ce délai, relancez la commande pour en obtenir un nouveau. Un Ctrl-C pendant l’attente n’enregistre rien, et un second Ctrl-C arrête la commande immédiatement. Utilisez --device sur un serveur auquel vous accédez en SSH, dans un conteneur, ou quand un agent de codage installe Clearcote pour vous : l’approbation a lieu dans votre propre navigateur, et rien de secret ne transite par le terminal, son historique ou une conversation. Si vous avez la clé sous la main sur votre propre machine, clearcote login fait tout aussi bien l’affaire : depuis la 0.40.0, la commande lit la clé sans l’afficher.

La commande clearcote

Les packages Python et Node installent une commande clearcote (avec une installation npm locale, lancez-la via npx clearcote …). Le package .NET n’en fournit pas.

clearcote install              # download + verify the browser now (CI, Docker builds)
clearcote info                 # this machine, SDK, key, cached builds, seats in use, a launch test, missing libraries
clearcote info --proxy <url>   # the exit IP, timezone and language a launch through this proxy would get
clearcote bench --proxy <url>  # what each browser costs here in CPU and RAM, page timings, how many fit at once
clearcote update               # fetch a newer build if one exists (newest open build, or current licensed)
clearcote clear-cache          # delete cached builds — old ones are kept until you do
clearcote login [key]          # clearcote logout removes the saved key
clearcote serve                # a standing CDP endpoint — see Deployment
clearcote connect [code]       # start the helper for the web Profile Manager — see below

Chaque commande accepte --help. Depuis le SDK 0.40.0, clearcote info teste le build que launch() exécuterait, y compris celui que désigne CLEARCOTE_BROWSER_VERSION, et indique la date d’expiration de la clé si elle a été enregistrée avec clearcote login --device (pour une clé collée, aucun service de licence n’en communique l’expiration). Depuis la 0.41.0, il indique aussi, sous Linux, quels systèmes d’écriture les polices que verrait un lancement savent dessiner (voir vos propres polices sous Linux). clearcote install --version 154 ou --channel preview sélectionne un build précis ; voir choisir un build. Ensuite, branchez-le sur Playwright ou Puppeteer.

Depuis la 0.56.0, clearcote info commence par la machine elle-même (processeur, mémoire, système d’exploitation, machine virtuelle ou conteneur, et présence d’une carte graphique avec laquelle le navigateur peut dessiner). clearcote bench lance --concurrency navigateurs (3 par défaut), charge --url pendant --duration secondes (30 par défaut), via --proxy s’il est indiqué, et indique ce que coûte chaque navigateur en threads CPU et en RAM sur cette machine, les temps de chargement, les erreurs, combien de navigateurs la machine fait tourner à la fois, à peu près, et quoi changer. Quand la mémoire libre semble trop faible, il lance moins de navigateurs (--force les lance tous), et chaque navigateur occupe une place de licence pendant qu’il tourne. Collez sa sortie dans une demande de support. En .NET, ClearcoteBench.RunAsync et ClearcoteHost.Info donnent le même rapport depuis le code.

Depuis la 0.61.0, clearcote connect démarre le Clearcote Helper dans ce terminal, pour que la version web du Profile Manager sur app.clearcotelabs.com puisse lancer vos profils sur cet ordinateur. Dans sa fenêtre Connect, choisissez I use the Clearcote SDK et lancez la commande affichée, avec son code à usage unique (npx clearcote connect 4F7-K2Q) : cet onglet se connecte tout seul, sans la page d'approbation. Au premier lancement, le SDK télécharge la version du helper qu'il fixe et vérifie son SHA-256. Gardez le terminal ouvert ; Ctrl+C ferme le helper et ses navigateurs.

macOS

Sur un Mac Apple Silicon (M1 ou plus récent, macOS 13 ou ultérieur) avec une clé de licence, le SDK (0.51.1+) télécharge le build macOS sous licence et le démarre nativement, comme sous Windows et Linux. C’est une preview, qui peut être en retard sur Windows et Linux : actuellement, il s’agit de 155.0.8059.39-r49, alors que ceux-ci exécutent 156.0.8078.47-r57. Sans clé de licence, le SDK (0.68.4+) télécharge le build ouvert 150 pour Apple Silicon (v0.1.0-pre.24, une version de Chromium derrière les builds ouverts pour Windows et Linux) et le démarre lui aussi nativement.

Sur un Mac Intel (et, avec le SDK 0.40.0 à 0.68.3, sur tout Mac sans clé de licence), launch() démarre l’image Docker de Clearcote (teamflatearth/clearcote:sdk-<SDK version>, une image linux/amd64 que Docker Desktop exécute sur Intel comme sur Apple silicon), s’y connecte et renvoie le même navigateur Playwright qu’un lancement local. Votre code ne change pas, et close() arrête et supprime le conteneur. Cela couvre launch() en Python (sync et async), Node et .NET (LaunchAsync) ; les autres points d’entrée, comme les contextes persistants et serve(), nécessitent toujours un binaire Clearcote : sur un Mac, exécutez-les donc directement dans l’image Docker.

from clearcote import launch

browser = launch(fingerprint="acct-1")   # on macOS: runs teamflatearth/clearcote:sdk-<version>
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()                          # stops and removes the container

• Docker Desktop doit être installé et lancé. Sinon, launch() lève DockerUnavailableError (.NET : DockerUnavailableException) avec un message qui indique quoi faire. Le premier lancement télécharge l’image et, avec une clé de licence, le dernier build, une seule fois, dans le volume clearcote-cache ; les lancements suivants démarrent en quelques secondes.
• Ce qui est transmis au conteneur : les options de persona, headless, proxy, args, version et la clé de licence (trouvée comme sur n’importe quelle autre machine, y compris celle qu’a enregistrée clearcote login). Une option que le conteneur ne peut pas recevoir est refusée nommément. La clé et le proxy parviennent au conteneur sous la forme d’un fichier qu’il lit une seule fois puis supprime : docker inspect ne les affiche donc pas, et un lancement avec une clé ou un proxy est refusé si le conteneur n’exécute pas le build sous licence ou n’utilise pas le proxy.
• Rien ne continue de tourner. Si votre programme se termine ou est tué sans close(), son conteneur s’arrête de lui-même environ 30 secondes après que plus rien n’y est connecté, et le lancement suivant supprime les conteneurs restants dont le programme a disparu. Les conteneurs qui appartiennent à d’autres programmes en cours d’exécution, à d’autres utilisateurs ou à d’autres machines ne sont jamais touchés. Depuis le SDK 0.41.0, close() ne rend la main qu’une fois que Docker a supprimé le conteneur et son volume : docker ps -a ne le liste donc plus ensuite.
• Chrome conserve sa sandbox (SDK 0.41.0+ avec une image à partir de sdk-0.41.0) : le lancement passe le profil seccomp de l’image, si bien que Chrome tourne avec sa sandbox dans le conteneur (voir la sandbox de Chrome). Il faut pour cela Docker sur un processeur x86_64 ; sur Apple silicon, l’image tourne en émulation et la sandbox reste désactivée pour l’instant.
• Le conteneur tourne sous Linux : sa persona par défaut est donc une persona Linux. Lisez Déploiement avant d’annoncer une autre plateforme depuis un conteneur.

Une image est publiée quelques minutes après la sortie de son SDK : juste après une mise à jour, le tag correspondant peut donc ne pas encore exister ; le message d’erreur le signale, et CLEARCOTE_DOCKER_IMAGE peut pointer vers un tag antérieur en attendant.

Installation manuelle (build ouvert)

Vous préférez le binaire brut ? GitHub Releases propose le build ouvert. Le build sous licence n’y est pas publié : il s’exécute via le SDK, clearcote serve ou l’image Docker, et ne démarre pas sans le jeton d’exécution fourni par le SDK.

1. Télécharger

Téléchargez la version v0.1.0-pre.* la plus récente — actuellement v0.1.0-pre.25 (Chromium 151.0.7922.108). Chaque version contient :

• clearcote-<version>-windows-x64.zip — le build Windows (Chromium + runtime + DLL VC++)
• clearcote-<version>-linux-x64.tar.xz — le build Linux
• les fichiers .sha256 et SHA256SUMS.txt — sommes de contrôle
• les fichiers .asc + clearcote-signing-key.asc — signatures GPG détachées et clé publique

2. Vérifier (recommandé)

Le build ouvert est conçu pour que vous n’ayez pas à nous croire sur parole. Avant l’extraction, vérifiez que le téléchargement correspond exactement à ce qui a été compilé et signé — voir Vérification.

3. Extraire

L’archive Windows est autonome : les DLL du runtime VC++ 2015–2022 sont incluses, elle tourne donc sur une machine Windows 10/11 vierge. L’archive Linux nécessite les bibliothèques d’exécution listées plus haut.

Expand-Archive clearcote-151.0.7922.108-windows-x64.zip -DestinationPath C:\clearcote

# you now have:
#   C:\clearcote\chrome.exe
#   C:\clearcote\chrome.dll  + runtime, locales, ICU, ANGLE, VC++ DLLs

4. Smoke test

Lancez-le sur une page de test d’empreinte avec une seed :

C:\clearcote\chrome.exe --fingerprint=seed-123 --fingerprint-platform=windows https://abrahamjuliot.github.io/creepjs/

Même seed --fingerprint ⇒ même identité à chaque lancement ; nouvelle seed ⇒ nouvelle identité. Pour que le navigateur renvoie les valeurs capturées sur une vraie machine plutôt que celles dérivées de la seed, importez un profil capturé — voir Flags d’empreinte. Ensuite, branchez-le sur Playwright ou Puppeteer.

Lancer avec Docker

L’image officielle exécute Clearcote en tant qu’endpoint CDP — récupérez-la et pointez-y n’importe quel client Playwright, Puppeteer ou browser-use via le Chrome DevTools Protocol, sans modifier votre code.

# Chrome's sandbox profile, shipped in the image
docker run --rm --tmpfs /opt/xdg-cache --entrypoint cat teamflatearth/clearcote /etc/clearcote/seccomp.json > clearcote-seccomp.json
docker run -d --rm --shm-size=1g -p 127.0.0.1:9222:9222 --security-opt seccomp=clearcote-seccomp.json -e CC_FINGERPRINT=user-7423 teamflatearth/clearcote   # CDP on http://localhost:9222

from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://localhost:9222")   # your code, unchanged
    page = browser.new_page(); page.goto("https://example.com")

Configurez la persona avec des variables d’environnement — CC_PLATFORM (windows/linux/macos/android), CC_FINGERPRINT (seed), CC_BRAND (Edge…), CC_ACCEPT_LANGUAGE, CC_TIMEZONE, CC_TLS_PROFILE. Sans CC_FINGERPRINT, chaque conteneur reçoit sa propre seed aléatoire, conservée d’un redémarrage à l’autre ; définissez cette variable pour choisir ou réutiliser une identité. L’image embarque le build ouvert ; ajoutez -e CLEARCOTE_LICENSE_KEY=cc_lic_… -v clearcote-cache:/opt/xdg-cache pour exécuter le dernier build sous licence, téléchargé une seule fois dans le volume. Le navigateur tourne en mode headed sur un écran virtuel (CC_HEADLESS=1 pour du pur headless), et l’image est en linux/amd64. Le Dockerfile est auditable — reconstruisez l’image vous-même. L’endpoint CDP donne le contrôle total du navigateur : ne l’exposez qu’à des réseaux de confiance (-p 127.0.0.1:9222:9222 le limite à la machine hôte). Plus de détails dans Déploiement.

Limites de téléchargement

Les téléchargements de la version sous licence sont limités par licence, pour qu'une configuration qui récupère l'archive complète à chaque démarrage ne s'emballe pas. Un lancement qui trouve la version dans son cache ne télécharge rien et ne compte jamais : seuls les vrais téléchargements comptent.

Au-delà d'une limite, le SDK reçoit HTTP 429 avec un corps JSON (code vaut DOWNLOAD_RATE_LIMITED (quota par version) ou DOWNLOAD_LIMIT_EXCEEDED (offre gratuite)) et un en-tête Retry-After : le nombre de secondes avant que la limite se réinitialise. Les lancements dont la version est déjà en cache continuent de fonctionner. Depuis le SDK 0.62.0, un lancement qui ne peut pas télécharger une nouvelle version démarre, au lieu d'échouer, la version la plus récente de la même version de Chromium déjà dans son cache, et attend Retry-After avant de retenter ce téléchargement. Un lancement épinglé à une révision exacte (r50) reçoit toujours cette version ou une erreur.

Vous atteignez ces limites quand beaucoup de machines ou de conteneurs neufs démarrent en même temps, chacun avec un cache vide. Téléchargez chaque version une fois par machine plutôt qu'à chaque démarrage : les démarrages sont aussi plus rapides, sans téléchargement d'environ 460 Mo :

• Gardez le cache sur un volume. Pointez CLEARCOTE_CACHE vers un dossier qui survit aux redémarrages. Les démarrages qui le partagent attendent le premier téléchargement et le réutilisent.
• Intégrez le navigateur à votre image. Lancez clearcote install au moment du build, pour que chaque conteneur démarre avec la version en place. Reconstruisez l'image lors d'une mise à jour.

# 1. a shared, persistent cache
docker run -v clearcote-cache:/clearcote-cache -e CLEARCOTE_CACHE=/clearcote-cache …

# 2. or in your Dockerfile: download once while the image is built (the key stays out of the layers)
ENV CLEARCOTE_CACHE=/opt/clearcote-cache
RUN --mount=type=secret,id=clearcote_key \
    CLEARCOTE_LICENSE_KEY="$(cat /run/secrets/clearcote_key)" clearcote install

Limites de personas

Chaque lancement récupère sa persona (l’empreinte que décrivent la seed et les options) auprès du service de personas. Chaque licence peut récupérer un nombre défini de personas différentes par jour. Récupérer une persona déjà utilisée aujourd’hui ne coûte rien : un ensemble fixe de profils peut donc être relancé aussi souvent que vous le voulez.

Une persona correspond à une seed avec un ensemble d’options d’empreinte (marque, plateforme, etc.) : la même seed en Chrome et en Edge compte donc deux fois. Le compteur est remis à zéro à 00:00 UTC. Au-delà de la limite, le lancement échoue avec HTTP 429 renvoyé par le service de personas (daily persona quota reached) jusqu’à la remise à zéro.

Vous atteignez cette limite quand chaque lancement utilise une seed aléatoire toute neuve. Réutilisez plutôt un ensemble fixe de seeds, par exemple une liste de quelques centaines de noms que vous faites tourner : chacune garde la même empreinte à chaque démarrage, et la relancer n’est jamais recomptée.

Configuration requise

• Windows 10 / 11 x64, ou Linux x64 (glibc) avec les bibliothèques d’exécution ci-dessus.
• macOS : sur Apple Silicon (macOS 13+), rien de plus (SDK 0.51.1+ avec une clé de licence, 0.68.4+ sans). Sur un Mac Intel, Docker Desktop, lancé, pour launch() (SDK 0.40.0+).
• Aucun redistribuable VC++ à installer séparément sous Windows — il est inclus dans l’archive.
• SDK : Node 20+, Python 3.8+ ou .NET 8. Chacun installe son propre driver Playwright (playwright-core, playwright, Microsoft.Playwright).
• Pour utiliser directement le binaire du build ouvert : votre installation existante de Playwright ou de Puppeteer (Clearcote remplace le navigateur, pas le driver).