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. Il n’existe pas de build macOS natif : sur macOS, launch() exécute l’image Docker de Clearcote pour vous (SDK 0.40.0+, 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                 # 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 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

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.

macOS

Il n’existe pas de build macOS natif. Depuis le SDK 0.40.0, launch() sous macOS 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.23 (Chromium 150.0.7871.114). 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-150.0.7871.114-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.

docker run -d --rm -p 127.0.0.1:9222:9222 -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.

Configuration requise

• Windows 10 / 11 x64, ou Linux x64 (glibc) avec les bibliothèques d’exécution ci-dessus.
• macOS (Intel ou Apple silicon) : 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).