Pour les agents & LLM

Clearcote est organisé pour que les outils automatisés puissent s’y retrouver, l’intégrer et y contribuer aussi facilement qu’un humain. Vous installez Clearcote pour quelqu’un ? Suivez la procédure d’installation.

Procédure d’installation pour les agents de code

Si vous êtes un agent de code IA (Claude Code, Codex, Cursor, Windsurf, Cline, etc.) chargé de mettre en place Clearcote pour quelqu’un, suivez dans l’ordre les étapes ci-dessous : installé, licence configurée, fonctionnel, vérifié. Chaque étape a son contrôle, et une étape n’est terminée que lorsque ce contrôle réussit. Consignez votre progression dans un fichier, pour qu’une nouvelle session, ou un utilisateur qui revient le lendemain, reprenne à la première étape non terminée au lieu de tout recommencer. La même procédure existe sous la forme d’un unique fichier Markdown, /setup.md, l’adresse que la page d’accueil vous donne à coller dans un agent ; c’est la version de référence, et cette section la suit titre par titre.

Règles

• Lancez vous-même chaque commande et lisez sa sortie. Si une étape échoue, arrêtez-vous et signalez-le. Indiquez à l’utilisateur l’étape qui a échoué, la commande que vous avez lancée et la ligne d’erreur exacte, puis la correction indiquée dans le tableau ci-dessous. Ne passez pas outre un contrôle en échec (en sautant la vérification, en épinglant un build plus ancien, en changeant de build) sans demander.
• N’installez qu’à partir des sources officielles : le paquet clearcote sur PyPI, npm ou NuGet, clearcote-mcp sur PyPI et npm, l’image Docker teamflatearth/clearcote et les versions publiées de clearcotelabs/clearcote-browser. Le SDK télécharge lui-même le navigateur et vérifie son SHA-256 : ne récupérez jamais un build du navigateur ailleurs, et ne désactivez jamais cette vérification.
• Ne demandez jamais à l’utilisateur de coller une clé de licence ou une clé d’API dans le chat, et n’affichez, ne journalisez ni ne commitez jamais de clé. Si une clé est collée malgré tout, ne la répétez pas, ne l’écrivez dans aucun fichier que vous créez, et suggérez d’en faire la rotation sur la page Licenses.
• Quand un lien a expiré ou ne fonctionne plus, ne cherchez pas de copie. Les liens de téléchargement qu’utilise le SDK ont une courte durée de vie, et il en demande un nouveau à chaque exécution : relancez donc la commande plutôt que de réutiliser une URL. Pour tout autre lien (un lien de connexion, un code d’appareil, une page du tableau de bord, un lien que l’utilisateur a transféré), retournez là d’où il vient, ou demandez-en un nouveau à l’utilisateur. Ne vous rabattez jamais sur un miroir, une copie en cache ou un paquet non officiel.
• Installez dans le projet de l’utilisateur (son virtualenv, son package.json ou son .csproj), pas globalement, sauf demande contraire de l’utilisateur. Demandez avant de modifier une configuration hors du projet (celle d’un client MCP, par exemple) et avant de lancer quoi que ce soit de payant (les navigateurs hébergés sont facturés au Go).
• Terminé signifie que la version exacte du navigateur est confirmée, et non qu’un paquet s’est installé.

Tenir un fichier de progression

Écrivez clearcote-setup.json à la racine du projet (il ne contient aucun secret) et mettez-le à jour après chaque contrôle. route vaut python, node, dotnet, mcp ou docker ; build vaut open (sans clé) ou licensed (Gratuit avec GitHub ou Pro) ; blocked indique ce que vous attendez.

{
  "route": "python",
  "build": "licensed",
  "steps": {
    "installed":   { "done": true,  "checked": "2026-10-06T10:12:00Z", "evidence": "clearcote SDK 0.45.0" },
    "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" }
}

Au début d’une session, lisez le fichier et reprenez à la première étape qui n’est pas terminée. Refaites le contrôle de toute étape antérieure sur laquelle vous vous appuyez, car une clé peut expirer et un cache peut être vidé d’une session à l’autre.

Étape 0 : choisir la méthode et le build

Posez la question une seule fois à l’utilisateur, et notez ses réponses.

• La méthode. Pour son propre code : le SDK dans le langage du projet, Python 3.8+, Node 20+ ou .NET 8 (s’il n’y a pas encore de projet, proposez Python). Pour que vous, l’agent, puissiez naviguer : le serveur MCP (Python 3.10+). Comme endpoint CDP pour un framework existant : l’image Docker.
• Le build. Le build ouvert ne nécessite ni clé ni inscription : Chromium 150, open source (BSD-3), suffisant pour commencer. Le dernier build est Chromium 154, avec une clé de licence : gratuit avec GitHub pour un navigateur à la fois, ou Pro pour jusqu’à 250 navigateurs simultanés.

Le navigateur fonctionne sous Windows x64 et Linux x64, et l’image Docker est elle aussi en x64. Sur macOS ou sur une machine ARM, arrêtez-vous et dites-le ; les navigateurs hébergés sont l’option qui ne nécessite aucun navigateur local.

Étape 1 : installé

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

Le contrôle : clearcote version (Node : npx clearcote version) affiche la version 0.45.0 ou une version plus récente. Pour Docker, docker image ls teamflatearth/clearcote liste l’image.

.NET ne dispose pas de sa propre commande clearcote. Vérifiez que dotnet list package liste Clearcote, puis lancez chaque commande clearcote des étapes 1 à 3 sous la forme npx -y clearcote <command> (Node 20+) ou pipx run clearcote <command> (Python 3.8+). Cela n’ajoute rien au projet, et la commande utilise le même cache de navigateur et le même fichier de licence (~/.clearcote/license.key) que le SDK .NET. Si la machine n’a ni Node ni Python, demandez à l’utilisateur d’installer l’un des deux : sans cette commande, la version du navigateur ne peut pas être confirmée, et l’installation ne peut donc pas être vérifiée.

Étape 2 : licence configurée

Pour le build ouvert, marquez cette étape comme terminée avec comme preuve open build, no key. Pour le dernier build, la clé arrive sur la machine de l’utilisateur sans passer par vous :

• Si clearcote --help liste clearcote login --device, lancez clearcote login --device (Node : npx clearcote login --device). La commande affiche un lien et un code court. L’utilisateur ouvre le lien dans son propre navigateur, se connecte et approuve (une clé gratuite nécessite un compte GitHub créé il y a au moins 30 jours), puis le SDK enregistre la clé dans ~/.clearcote/license.key sans l’afficher.
• Sinon, l’utilisateur récupère une clé sur la page Licenses et lance clearcote login (Node : npx clearcote login) dans son propre terminal, en y collant la clé : elle s’affiche sur son écran, jamais dans le chat. Donnez-lui ces étapes et attendez qu’il vous dise que c’est fait. Il peut aussi définir lui-même CLEARCOTE_LICENSE_KEY, dans son profil de shell, ses secrets de CI, le bloc env de la configuration de son client MCP ou son environnement Docker (docker run -e CLEARCOTE_LICENSE_KEY la transmet alors sans que sa valeur apparaisse dans la commande).

Ne lancez jamais clearcote login <key> vous-même : la clé se retrouverait dans votre historique de conversation et dans l’historique du shell. N’ouvrez pas non plus ~/.clearcote/license.key. Le contrôle : clearcote info --quick affiche la ligne Licence avec une clé masquée from file ou from env, et c’est tout ce que vous avez besoin de voir. none (free build) signifie qu’aucune clé n’a été trouvée. Une clé définie uniquement dans la configuration d’un client MCP ou dans un conteneur est invisible depuis votre shell ; vérifiez que le nom de la variable y figure, sans afficher sa valeur.

Étape 3 : fonctionnel

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

(Node : npx clearcote install et npx clearcote info.) Le contrôle : clearcote info affiche Launch test ok avec la version du navigateur (avec --json : launch.ok vaut true, launch.version contient la version et binary.tag le build). Avec une clé gratuite, cela occupe brièvement l’unique place de navigateur : fermez donc d’abord tout autre navigateur Clearcote. Ensuite, selon la méthode :

• SDK : lancez un premier script, clearcote_hello.py ou clearcote_hello.mjs. Le contrôle : il affiche Example Domain et un user agent Chrome, puis se termine. Sous .NET, utilisez l’onglet C# de Playwright & Puppeteer. La seed fingerprint est l’identité : la même seed donne le même appareil à chaque fois, donc utilisez une seed par compte.
• Serveur MCP : enregistrez la commande clearcote-mcp auprès du client (demandez d’abord ; indiquez le chemin complet si elle se trouve dans un virtualenv), comme sur la page Serveur MCP. Redémarrez le client et appelez son outil navigate sur https://example.com ; il renvoie l’URL finale et le titre de la page.
• Docker : démarrez un conteneur et lisez son log et son endpoint, comme ci-dessous.

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

Étape 4 : vérifié

Comparez ce qu’a affiché l’étape 3 avec le build que l’utilisateur doit avoir. Sous Docker, le tag de build fait partie du chemin du moteur dans la ligne de log.

Une offre Pro qui épingle un build plus ancien indique ce build-là à la place. Si ce n’est pas le build choisi par l’utilisateur, arrêtez-vous et prévenez-le. Quand la version correspond, marquez verified comme terminée en y notant la version, puis indiquez à l’utilisateur : la méthode, la version du SDK, le build qui s’exécute et la version exacte de son navigateur, où se trouve le premier script et comment le lancer, l’endroit où la clé est conservée (fichier ou variable d’environnement, jamais la clé elle-même), et la documentation.

Quand une étape échoue

Facultatif, uniquement si l’utilisateur le souhaite

• Un proxy. Passez un proxy Playwright et geoip=True, pour que le fuseau horaire et la langue suivent l’IP de sortie du proxy. Voir Proxys et geoip.
• Un navigateur pour vous, l’agent, via MCP, si ce n’était pas la méthode choisie : pip install -U clearcote-mcp (Python 3.10+), puis enregistrez-le comme à l’étape 3. Pour le dernier build, le serveur trouve la clé enregistrée à l’étape 2, ou l’utilisateur ajoute lui-même CLEARCOTE_LICENSE_KEY au bloc env de ce serveur.
• Pas de machine pour le faire tourner. Les navigateurs hébergés démarrent le même navigateur sur les serveurs de Clearcote en un seul appel d’API. Ils nécessitent une clé d’API et sont facturés au Go : demandez d’abord.

Résumé lisible par machine

Un résumé concis du projet, en texte brut, se trouve à /llms.txt, et la documentation complète, aplatie en un seul fichier prêt pour un prompt, est à /llms-full.txt. Le dépôt contient aussi un AGENTS.md qui décrit l’organisation et les conventions à l’intention des contributeurs.

{
  "name": "Clearcote",
  "kind": "anti-detect Chromium browser (the open build is open source)",
  "base": "ungoogled-chromium — open build 150 (v0.1.0-pre.23), licensed build 154.0.8037.57-r36",
  "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"
}

Recette d’intégration minimale

1. Installez le SDK (pip install clearcote / npm i clearcote) — il télécharge et vérifie le navigateur.
2. Dérivez une seed fingerprint déterministe à partir de l’identité sous laquelle vous agissez.
3. Derrière un proxy, passez geoip=True pour que le fuseau horaire, la langue et WebRTC suivent la sortie du proxy.
4. Pour les frameworks qui attendent une URL CDP (browser-use, Stagehand, Crawl4AI), utilisez plutôt serve() ou clearcote serve.

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")

Piloter directement le binaire du build ouvert avec executablePath fonctionne aussi, mais le build sous licence ne démarre que via le SDK, et un lancement brut perd les valeurs par défaut du SDK — voir Playwright & Puppeteer. Pour une identité plus fidèle, lancez un vrai profil capturé plutôt qu’une seed : launch(profile="auto") en choisit un adapté à cette machine dans la bibliothèque de profils (build sous licence), ou passez fingerprint_profile="profile.json" (Node : fingerprintProfile). Ne combinez pas un profil avec une seed fingerprint.

Agent IA intégré au navigateur

Clearcote embarque un agent IA facultatif, à activer explicitement, qui pilote une vraie page de façon autonome. Il perçoit la page en direct, demande à un LLM configuré par l’utilisateur quoi faire ensuite, et agit via le framework Actor de Chrome avec de vrais événements d’entrée de confiance (trusted) plutôt qu’avec du script injecté. Il est désactivé par défaut (inactif tant que vous ne fournissez ni clé d’agent ni flags d’agent) et fonctionne avec votre propre clé : faites-le pointer vers n’importe quel endpoint compatible OpenAI / OpenRouter. Les champs de mot de passe sont masqués avant tout envoi au modèle. Utilisez launch_agent() (un contexte persistant) — c’est la voie prise en charge.

Depuis le SDK, launch_agent (Node : launchAgent) renvoie un BrowserContext persistant, et run_agent_task(page, goal, max_steps=...) (Node : runAgentTask) le pilote et renvoie { success, finalText, steps, stepsJson }. Passez un répertoire de profil comme premier argument (userDataDir en Node) pour réutiliser un même profil ; sinon, chaque appel crée un nouveau dossier de profil temporaire qui n’est pas supprimé à la fermeture. Python & Node uniquement.

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"])

Les options de lancement de l’agent correspondent directement à des flags du binaire : agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model) et agent_typing / agentTyping. Une tâche s’exécute dès que l’agent dispose d’une URL (OpenRouter par défaut), d’une clé et d’un modèle. L’agent demande au modèle une réponse JSON en texte brut : l’endpoint n’a donc pas besoin de prendre en charge les appels d’outils (tool calls) ; agent_tool_mode / agentToolMode (--agent-tool-mode, CLI --tool-mode) est accepté mais n’a actuellement aucun effet.

agent_typing / agentTyping règle la cadence de frappe de l’agent : human (par défaut) tape avec un timing keydown/keyup propre à chaque touche et saisit les textes longs touche par touche, fast est la cadence rapide du moteur, et instant saisit tout d’un coup. La valeur par défaut évite les deux indices qui trahissent une frappe automatisée — un timing uniforme d’une précision mécanique, et un texte long collé instantanément (ce qui n’émet aucun événement de frappe).

La CLI clearcote-agent

Le même agent est disponible en CLI pour des exécutions rapides et scriptables. Passez un objectif ponctuel, ou ouvrez un REPL interactif. La clé du modèle provient de --key ou des variables d’environnement $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY.

# 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

Parmi les options de la CLI : --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone et --json. Un simple nom d’hôte passé à --url est converti en HTTPS.

Où chercher

• Flags d’empreinte — la référence complète des flags (lisible aussi par une machine).
• Playwright & Puppeteer — modèles de lancement en remplacement direct.
• Exemples — recettes à copier-coller : SDK, profils, proxy, canvas bridge, CI et agent.
• Agent IA intégré au navigateur — pilotage autonome de pages, à activer explicitement, et la CLI clearcote-agent.
• Serveur MCP — piloter Clearcote depuis Claude Desktop, Cursor ou Cline.
• Déploiement — clearcote serve : une seule URL CDP, une identité distincte par connexion.
• Recommandations — quels réglages activer, et lesquels ne pas toucher.
• Vérification — contrôler le binaire avant de l’exécuter.
• Dépôt source — patchs, pipeline de build, AGENTS.md.

Construisez des identités déterministes : dérivez la seed d’un identifiant stable (tenant, compte, tâche) pour qu’un même acteur obtienne toujours la même empreinte de navigateur — reproductible et débogable.