Local ou cloud : un seul SDK
Le même launch() qui lance Clearcote sur votre machine le lance sur nos serveurs. Passez cloud=True (Python) ou cloud: true (Node), ou définissez CLEARCOTE_CLOUD=1, et vous récupérez le même objet Playwright Browser, connecté à un navigateur hébergé. Le reste de votre script ne change pas.
Exécuter un script dans le cloud
Il vous faut le SDK 0.34.0 ou plus récent et une clé d’API créée sur la page API keys. Placez la clé dans CLEARCOTE_API_KEY, puis :
from clearcote import launch
browser = launch(cloud=True, fingerprint="acct-1", country="de")
page = browser.contexts[0].new_page()
page.goto("https://example.com")
print(page.title())
browser.close() # ends the cloud sessionDerrière l’appel, le SDK crée une session avec POST /api/v1/browsers, s’y connecte via CDP et configure le humanize comme le fait un lancement local. Ouvrez les pages dans browser.contexts[0] : c’est lui qui porte le profil de la session. browser.new_page() fonctionne aussi, mais ouvre un contexte séparé sans les cookies du profil (le SDK y désactive quand même le viewport émulé de Playwright, comme en local).
La session hébergée derrière le navigateur se trouve dans browser.cloud_session en Python et cloudSessionOf(browser) en Node (aussi browser.cloudSession) : la réponse de création avec son id, son worker et son expiresAt, sans la connectUrl à usage unique. Utilisez l’id avec le client Cloud pour le passage de relais et les enregistrements et événements.
Basculer avec des variables d’environnement
Omettez cloud dans l’appel et c’est l’environnement qui décide : un même script tourne en local sur votre portable et dans le cloud en production, sans changer le code.
| Variable | Signification |
|---|---|
CLEARCOTE_CLOUD | 1, true ou yes : un launch() sans argument cloud démarre un navigateur cloud. Toute autre valeur, ou non définie : un navigateur local. |
CLEARCOTE_API_KEY | Votre clé cc_live_…. Nécessaire pour chaque appel cloud. |
CLEARCOTE_API_URL | L’API à contacter. Par défaut https://www.clearcotelabs.com ; ne la changez que pour un control plane de développement. Elle doit être en https:// ; le simple http:// n’est accepté que pour cette machine (localhost, 127.0.0.1, ::1), afin que la clé ne traverse jamais un réseau sans chiffrement. |
export CLEARCOTE_API_KEY=cc_live_...
python scrape.py # a local browser
CLEARCOTE_CLOUD=1 python scrape.py # the same script on a hosted browserUn argument explicite l’emporte toujours : cloud=False / cloud: false lance en local, quoi que dise CLEARCOTE_CLOUD.
Options
En mode cloud, launch() accepte les options de POST /api/v1/browsers. Node utilise les noms de l’API tels quels ; Python utilise le snake_case, et le SDK les renomme. Les règles complètes de chaque option se trouvent dans la référence Navigateurs hébergés.
| Python | Node et API | Signification |
|---|---|---|
identity | identity | Un libellé par compte : le même appareil et la même IP résidentielle tant que cette IP reste en ligne. |
fingerprint | fingerprint | Seed de l’appareil. Le même seed donne le même profil d’appareil. |
light_stealth | lightStealth | Par défaut true. |
platform | platform | windows, macos, linux ou android. |
brand | brand | Chrome, Edge, Opera ou Vivaldi. |
timezone | timezone | Nom IANA, par exemple Europe/Berlin. |
locale, accept_language | locale | Accept-Language, par exemple de-DE,de. accept_language (Node : acceptLanguage) est un alias. |
geoIdentity | geoIdentity | Default "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event. |
geoip | geoip | Le fuseau horaire et la langue suivent l’IP de sortie. |
proxy | proxy | "managed" (par défaut), { server, username, password }, ou une URL comme http://user:pass@host:8080, que le SDK découpe pour vous en cet objet. |
country | country | Pays de sortie dans le pool résidentiel géré. |
state | state | État ou région de sortie dans le pool géré. Nécessite country. |
city | city | Ville de sortie dans le pool géré. Nécessite state. |
proxy_session | proxySession | Libellé sticky : le même libellé retrouve plus tard la même IP de sortie. |
timeout_sec | timeoutSec | Limite stricte de durée de la session, en secondes. |
idle_timeout_sec | idleTimeoutSec | Met fin à la session après ce délai sans commande CDP. |
max_gb | maxGb | Arrête la session après ce volume de trafic. |
headless | headless | Par défaut true. Avec false (une vraie fenêtre), la page indique l’écran du serveur, pas la taille d’écran de l’identité. |
humanize | humanize | Default true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input". |
keep_alive | keepAlive | Garde le navigateur en marche après votre déconnexion. |
version | version | Lance une version précise de Clearcote. |
profile | profile | Un profil cloud : "name" pour le charger, { name, persist: true } pour aussi l’enregistrer en retour. |
url | url | Ouverte dans le premier onglet avant que vous receviez le navigateur. |
adblock | adblock | Refuse les hôtes publicitaires et de suivi connus avant leur chargement. |
solve_sliders | solveSliders | Par défaut true : les challenges « slide to verify » sont glissés pour vous. false désactive cela ; les SDK 0.35.0 et antérieurs refusent ce nom (c’est toujours actif pour eux). |
solve_checkboxes | solveCheckboxes | Par défaut true : les cases « verify you are human » sont cochées pour vous. false désactive cela ; les SDK 0.36.2 et antérieurs refusent ce nom (c’est toujours actif pour eux). |
solve_press_hold | solvePressHold | Par défaut true : les boutons de vérification « press and hold » sont maintenus pour vous jusqu’à ce qu’ils signalent la fin. false désactive cela ; les SDK 0.49.0 et antérieurs refusent ce nom (c’est toujours actif pour eux). |
challenge_service | challengeService | Désactivé par défaut. true, ou { categories, sites, key, apiKey, mode, maxSolves, maxSpendEur } (Python accepte aussi max_solves, max_spend_eur, api_key) : les challenges que les actions gratuites ne résolvent pas partent vers un service de résolution, avec votre clé ou la nôtre. Nécessite le SDK 0.38.0 ou plus récent. |
record | record | Enregistre un MP4 de la session. |
note | note | Votre libellé pour la session. |
worker | worker | Démarre sur le même serveur qu’une session précédente. |
humanize | humanize | Non défini ou True (SDK 0.44.0+) : le humanize du SDK lui-même, pour la souris, le clavier et le défilement, comme pour un lancement local, celui du serveur étant désactivé. False : aucun. Avant 0.44.0, sans valeur, c’était au navigateur hébergé de s’en charger, et il ne déplace que la souris. |
show_cursor | showCursor | Affiche un point rouge qui suit la souris, pour observer ou déboguer. Côté SDK, comme humanize. |
api_key, api_url | apiKey, apiUrl | Le compte et le serveur d’API pour ce lancement. Par défaut CLEARCOTE_API_KEY et CLEARCOTE_API_URL. Jamais envoyés comme options. |
timeout, slow_mo | timeout, slowMo | Les options propres à Playwright pour la connexion CDP, en millisecondes. Non envoyées à l’API. |
Ce qui reste identique, ce qui change
Identique :
- Vous obtenez un objet Playwright.
launch()renvoie unBrowseretlaunch_persistent_context()unBrowserContext, en synchrone ou en asynchrone, exactement comme en local. - Les entrées humanisées sont actives par défaut. Depuis le SDK 0.44.0, un lancement cloud humanise dans le SDK, comme un lancement local avec
humanize=True: la souris suit des trajectoires humaines, les touches sont tapées une à une, le défilement se fait par crans de molette, et les clics par coordonnées sont joués par le moteur lui-même. Chaque étape traverse le réseau, c’est donc plus lent que des entrées simples ; passezhumanize=Falsepour des entrées simples et rapides. Dans les deux cas, le lancement désactive le mouvement de souris propre au navigateur hébergé, pour qu’un seul des deux déplace le curseur. Les clients qui se connectent sans le SDK conservent celui du navigateur hébergé, qui déplace la souris sur le serveur, maintient chaque clic pendant une durée de pression humaine et transforme les grands défilements en crans de molette entiers. - Le même moteur. Les sessions hébergées exécutent les mêmes versions de Clearcote que celles que le SDK télécharge : les options de persona ont donc le même sens aux deux endroits, et
versionépingle le même build.
Différent :
- Les options réservées au local sont refusées.
executable_path,args,user_data_dir,extensions,ignore_default_argset les autres options qui n’ont de sens que pour un binaire sur votre machine lèventValueError("<name> is not available for cloud browsers")en Python (une erreur avec le même message en Node) au lieu d’être ignorées. - Des profils au lieu de dossiers. Un navigateur cloud n’a pas de dossier sur votre disque. Pour conserver les cookies et le stockage des sites d’une exécution à l’autre, utilisez un profil cloud nommé (voir ci-dessous).
profiledésigne un profil cloud. En local,profilechoisit un profil d’appareil capturé ("auto"). En mode cloud, il nomme un profil cloud enregistré : cookies, localStorage et IndexedDB.- Valeurs par défaut hébergées. Une session cloud part des valeurs par défaut hébergées : une persona Windows,
lightStealthactivé, un seed, un fuseau horaire et une langue qui suivent l’IP de sortie, le module Widevine que possède un Google Chrome, des mouvements de souris humains, et une IP de sortie résidentielle, sauf si vous passez votre propreproxy. - Fermeture.
browser.close()se déconnecte, et la session prend fin quand son client s’en va ; par sécurité, le SDK l’arrête aussi via l’API. Aveckeep_alive/keepAlive, le navigateur continue de tourner, jusqu’à ce que vous l’arrêtiez ou qu’une limite le fasse. - Limites de l’hébergement. Pas de
file://, pas d’extensions, pas de réseaux privés, les téléchargements sont récupérés via la connexion (voir Télécharger des fichiers), etpage.on("console")reste muet. Voir les limites. - Facturation. Un navigateur cloud est facturé comme n’importe quelle session hébergée, au Go de trafic, sur votre solde prépayé. Un navigateur local ne coûte rien au-delà de votre licence.
Un contexte persistant sur un profil cloud
launch_persistent_context() avec cloud=True prend un nom de profil au lieu d’un dossier. Il renvoie le premier contexte d’une session cloud démarrée avec profile: { name, persist: true } : la session charge le profil, et fermer le contexte met fin à la session et y enregistre les cookies et le stockage des sites.
from clearcote import launch_persistent_context
ctx = launch_persistent_context(cloud=True, profile="shop-account", country="de")
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://shop.example.com/account")
ctx.close() # ends the session and saves "shop-account"Passer un user_data_dir avec cloud=True lève une ValueError qui vous renvoie vers profile=. Une seule session à la fois peut enregistrer dans un profil. Pour créer un profil à partir de cookies que vous avez déjà, utilisez la synchronisation des cookies.
Le client Cloud
Tout le reste de l’API a son client : sessions, exécutions d’agent, profils et webhooks. Il lit CLEARCOTE_API_KEY et CLEARCOTE_API_URL, ou les prend en arguments. Le client Python n’utilise que la bibliothèque standard ; AsyncCloud a les mêmes méthodes pour asyncio.
from clearcote.cloud import Cloud, CloudError
cloud = Cloud() # or Cloud(api_key="cc_live_...", base_url="https://www.clearcotelabs.com")
session = cloud.browsers.create(country="de", record=True)
print(session["id"], session["connectUrl"])
try:
cloud.browsers.stop(session["id"])
except CloudError as e:
print(e.status, e.code, e.message)| Namespace | Méthodes |
|---|---|
browsers | create(**options), get(id), list(status=None, note=None, limit=None, before=None), stop(id), live(id, control=False), share(id, control=None, minutes=None, recording=None), handoff(id, reason=None, timeout_sec=None), handoff_done(id), wait_handoff(id, timeout=None, poll=2.0), events(id, after=0, limit=None), recording_url(id), download_recording(id, path) |
runs | create(task, url=None, schema=None, secrets=None, wait=True, timeout=None, poll=1.5, on_update=None, **options), get(id), list(limit=None, before=None), cancel(id), wait(id, timeout=None, poll=1.5, on_update=None) |
profiles | list(), get(name), delete(name), import_cookies(name, cookies, mode="merge"), sync(name, …) |
webhooks | create(url, events=None, description=None), list(), delete(id), test(id) |
Chaque méthode renvoie le JSON de l’endpoint tel quel : un dict en Python, un objet simple en Node. Les appels de liste renvoient l’objet de l’API, par exemple { balanceEur, sessions } ou { runs }, pas une liste nue. Les durées que le SDK attend lui-même (timeout, poll) sont en secondes dans les deux langages.
Node a les mêmes méthodes en camelCase (handoffDone, waitHandoff, importCookies, recordingUrl, downloadRecording), avec les arguments optionnels regroupés dans un objet : live(id, { control }), events(id, { after, limit }), runs.create(task, { url, schema, country, … }), importCookies(name, cookies, { mode }), webhooks.create(url, { events }). Un appel en échec lève CloudError avec le status HTTP (0 quand l’API était injoignable), le code de l’API et son message ; les codes sont listés sous Erreurs. Une attente qui dépasse son timeout lève à la place CloudTimeoutError, dont last contient le dernier état lu par le SDK ; l’exécution ou le passage de relais continue sur le serveur. Une option invalide lève ValueError en Python (une Error en Node) avant tout envoi. Le SDK exporte aussi verify_webhook / verifyWebhook pour les signatures de webhook.
La commande clearcote cloud
La commande clearcote fournie avec le SDK (pip install clearcote, ou npx clearcote) a un groupe cloud pour la même API :
# an agent run: prints the result when it finishes
clearcote cloud run "Find the price of the cheapest plan" --url https://example.com/pricing \
[--schema schema.json] [--secret name=value]... [--secret-domain name=host]... [--handoff] [--record] [--json]
# sessions
clearcote cloud sessions
clearcote cloud stop <id>
clearcote cloud events <id>
clearcote cloud recording <id> -o session.mp4
# copy cookies into a cloud profile (--domain or --all-domains is required)
clearcote cloud profile sync <name> (--from-profile DIR | --from-cdp URL | --from-file state.json | --login URL) \
(--domain example.com... | --all-domains) [--replace]
# webhooks
clearcote cloud webhooks add https://example.com/hooks/clearcote [--event run.finished]...
clearcote cloud webhooks list
clearcote cloud webhooks rm <id>
clearcote cloud webhooks test <id>Chaque commande accepte --json pour afficher la réponse de l’API au lieu d’un résumé. run attend le résultat et ne se termine avec 0 que si l’exécution a le statut succeeded (1 sinon, 2 pour une erreur d’utilisation), elle fonctionne donc dans un script shell. Sans -o, recording enregistre dans <id>.mp4. Lancez clearcote cloud --help pour voir tous les flags.
Chaque commande a sa propre page : exécutions, enregistrements et événements, synchronisation de profils et webhooks.
MCP : un navigateur cloud pour votre assistant IA
Le serveur MCP a le même interrupteur. Avec CLEARCOTE_CLOUD=1 et CLEARCOTE_API_KEY dans son env, le navigateur partagé que pilotent ses outils est un navigateur cloud. Avec une clé d’API définie, il obtient aussi un outil run_task qui confie une tâche entière à une exécution d’agent et renvoie le JSON du résultat.
{
"mcpServers": {
"clearcote": {
"command": "npx",
"args": ["-y", "clearcote-mcp"],
"env": { "CLEARCOTE_CLOUD": "1", "CLEARCOTE_API_KEY": "cc_live_..." }
}
}
}