Local o en la nube: un solo SDK
El mismo launch() que inicia Clearcote en tu máquina lo inicia en nuestros servidores. Pasa cloud=True (Python) o cloud: true (Node), o define CLEARCOTE_CLOUD=1, y recibes el mismo Browser de Playwright, conectado a un navegador alojado. El resto de tu script queda igual.
Ejecuta un script en la nube
Necesitas el SDK 0.34.0 o posterior y una clave de API de la página API keys. Pon la clave en CLEARCOTE_API_KEY y luego:
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 sessionDetrás de la llamada, el SDK crea una sesión con POST /api/v1/browsers, se conecta a ella por CDP y configura el humanize como lo hace un inicio local. Abre las páginas en browser.contexts[0]: lleva el perfil de la sesión. browser.new_page() también funciona, pero abre un contexto aparte sin las cookies del perfil (el SDK igual desactiva ahí el viewport emulado de Playwright, como en local).
La sesión alojada detrás del navegador está en browser.cloud_session en Python y en cloudSessionOf(browser) en Node (también browser.cloudSession): la respuesta de creación con su id, worker y expiresAt, sin la connectUrl de un solo uso. Usa el id con el cliente Cloud para el traspaso y para grabaciones y eventos.
Cambia con variables de entorno
Si omites cloud en la llamada, decide el entorno: así un mismo script corre en local en tu laptop y en la nube en producción sin cambiar el código.
| Variable | Significado |
|---|---|
CLEARCOTE_CLOUD | 1, true o yes: un launch() sin argumento cloud inicia un navegador en la nube. Cualquier otro valor, o sin definir: uno local. |
CLEARCOTE_API_KEY | Tu clave cc_live_…. Necesaria para cada llamada a la nube. |
CLEARCOTE_API_URL | La API con la que hablar. Por defecto https://www.clearcotelabs.com; cámbiala solo para un control plane de desarrollo. Debe ser https://; el http:// simple solo se acepta para esta máquina (localhost, 127.0.0.1, ::1), para que la clave nunca cruce una red sin cifrar. |
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 argumento explícito siempre gana: cloud=False / cloud: false inicia en local diga lo que diga CLEARCOTE_CLOUD.
Opciones
En modo nube, launch() acepta las opciones de POST /api/v1/browsers. Node usa los nombres de la API tal cual; Python usa snake_case y el SDK los renombra. Las reglas completas de cada opción están en la referencia de navegadores alojados.
| Python | Node y API | Significado |
|---|---|---|
identity | identity | Una etiqueta por cuenta: el mismo dispositivo y la misma IP residencial mientras esa IP siga en línea. |
fingerprint | fingerprint | Seed del dispositivo. El mismo seed da el mismo perfil de dispositivo. |
light_stealth | lightStealth | Por defecto true. |
platform | platform | windows, macos, linux o android. |
brand | brand | Chrome, Edge, Opera o Vivaldi. |
timezone | timezone | Nombre IANA, por ejemplo Europe/Berlin. |
locale, accept_language | locale | Accept-Language, por ejemplo de-DE,de. accept_language (Node: acceptLanguage) es 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 | La zona horaria y el idioma siguen a la IP de salida. |
proxy | proxy | "managed" (el valor por defecto), { server, username, password } o una URL como http://user:pass@host:8080, que el SDK divide por ti en ese objeto. |
country | country | País de salida en el pool residencial gestionado. |
state | state | Estado o región de salida en el pool gestionado. Requiere country. |
city | city | Ciudad de salida en el pool gestionado. Requiere state. |
proxy_session | proxySession | Etiqueta sticky: la misma etiqueta recupera más tarde la misma IP de salida. |
timeout_sec | timeoutSec | Límite estricto de duración de la sesión, en segundos. |
idle_timeout_sec | idleTimeoutSec | Termina la sesión tras este tiempo sin ningún comando CDP. |
max_gb | maxGb | Detiene la sesión tras esta cantidad de tráfico. |
headless | headless | Por defecto true. Con false (una ventana real), la página informa la pantalla del propio servidor, no el tamaño de pantalla de la identidad. |
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 | Mantiene el navegador en ejecución después de que te desconectas. |
version | version | Ejecuta una versión concreta de Clearcote. |
profile | profile | Un perfil en la nube: "name" para cargarlo, { name, persist: true } para además guardarlo de vuelta. |
url | url | Se abre en la primera pestaña antes de que recibas el navegador. |
adblock | adblock | Rechaza hosts conocidos de anuncios y rastreadores antes de que carguen. |
solve_sliders | solveSliders | Por defecto true: los desafíos “slide to verify” se arrastran por ti. false lo desactiva; el SDK 0.35.0 y anteriores rechazan el nombre (para ellos siempre está activo). |
solve_checkboxes | solveCheckboxes | Por defecto true: las casillas “verify you are human” se marcan por ti. false lo desactiva; el SDK 0.36.2 y anteriores rechazan el nombre (para ellos siempre está activo). |
solve_press_hold | solvePressHold | Por defecto true: los botones de verificación “press and hold” se mantienen pulsados por ti hasta que indican que terminaron. false lo desactiva; el SDK 0.49.0 y anteriores rechazan el nombre (para ellos siempre está activo). |
challenge_service | challengeService | Desactivado por defecto. true, o { categories, sites, key, apiKey, mode, maxSolves, maxSpendEur } (Python también acepta max_solves, max_spend_eur, api_key): los desafíos que las acciones gratuitas no pueden resolver van a un servicio de resolución, con tu clave o la nuestra. Requiere el SDK 0.38.0 o posterior. |
record | record | Graba un MP4 de la sesión. |
note | note | Tu etiqueta para la sesión. |
worker | worker | Inicia en el mismo servidor que una sesión anterior. |
humanize | humanize | Sin definir o True (SDK 0.44.0+): el humanize propio del SDK, con mouse, teclado y desplazamiento, como en un inicio local, con el del servidor desactivado. False: ninguno. Antes de 0.44.0, sin definir lo dejaba en manos del navegador alojado, que solo mueve el mouse. |
show_cursor | showCursor | Muestra un punto rojo que sigue al mouse, para observar o depurar. Del lado del SDK, como humanize. |
api_key, api_url | apiKey, apiUrl | La cuenta y el servidor de API para este inicio. Por defecto CLEARCOTE_API_KEY y CLEARCOTE_API_URL. Nunca se envían como opciones. |
timeout, slow_mo | timeout, slowMo | Las opciones propias de Playwright para la conexión CDP, en milisegundos. No se envían a la API. |
Qué se mantiene igual y qué cambia
Igual:
- Obtienes un objeto de Playwright.
launch()devuelve unBrowserylaunch_persistent_context()unBrowserContext, síncrono o asíncrono, exactamente como en local. - La entrada humanizada está activada por defecto. Desde el SDK 0.44.0, un inicio en la nube humaniza en el SDK, como un inicio local con
humanize=True: el mouse se mueve por trayectorias humanas, las teclas se escriben de una en una, el desplazamiento va por pasos de la rueda y los clics por coordenadas los reproduce el propio motor. Cada paso cruza la red, así que es más lento que la entrada simple; pasahumanize=Falsepara una entrada simple y rápida. En ambos casos, el inicio desactiva el movimiento de mouse propio del navegador alojado, para que solo uno de los dos mueva el cursor. Los clientes que se conectan sin el SDK conservan el del navegador alojado, que mueve el mouse en el servidor, mantiene cada clic durante un tiempo de pulsación humano y convierte los desplazamientos grandes en pasos completos de la rueda. - El mismo motor. Las sesiones alojadas ejecutan las mismas versiones de Clearcote que descarga el SDK, así que las opciones de persona significan lo mismo en ambos lugares, y
versionfija el mismo build.
Diferente:
- Las opciones solo locales se rechazan.
executable_path,args,user_data_dir,extensions,ignore_default_argsy las demás opciones que solo tienen sentido para un binario en tu máquina lanzanValueError("<name> is not available for cloud browsers")en Python (un error con el mismo mensaje en Node) en lugar de ignorarse. - Perfiles en lugar de carpetas. Un navegador en la nube no tiene carpeta en tu disco. Para conservar cookies y almacenamiento de sitios entre ejecuciones, usa un perfil en la nube con nombre (abajo).
profilesignifica un perfil en la nube. En local,profileelige un perfil de dispositivo capturado ("auto"). En modo nube nombra un perfil en la nube guardado: cookies, localStorage e IndexedDB.- Valores por defecto alojados. Una sesión en la nube parte de los valores por defecto alojados: una persona de Windows,
lightStealthactivado, un seed, zona horaria e idioma que siguen a la IP de salida, el módulo Widevine que tiene un Google Chrome, movimiento humano del mouse y una IP de salida residencial, salvo que pases tu propioproxy. - Cierre.
browser.close()se desconecta, y la sesión termina cuando su cliente se va; el SDK además la detiene por la API para asegurarse. Conkeep_alive/keepAliveel navegador sigue en ejecución, hasta que lo detengas tú o lo haga un límite. - Límites del alojamiento. Sin
file://, sin extensiones, sin redes privadas, las descargas se obtienen a través de la conexión (consulta Descargar archivos) ypage.on("console")no emite nada. Consulta los límites. - Facturación. Un navegador en la nube se factura como cualquier sesión alojada, por GB de tráfico de tu saldo prepago. Un navegador local no cuesta nada más allá de tu licencia.
Un contexto persistente sobre un perfil en la nube
launch_persistent_context() con cloud=True recibe un nombre de perfil en lugar de una carpeta. Devuelve el primer contexto de una sesión en la nube iniciada con profile: { name, persist: true }: la sesión carga el perfil, y cerrar el contexto termina la sesión y guarda en él las cookies y el almacenamiento de sitios.
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"Pasar un user_data_dir junto con cloud=True lanza un ValueError que te remite a profile=. Solo una sesión a la vez puede guardar en un perfil. Para crear un perfil a partir de cookies que ya tienes, usa la sincronización de cookies.
El cliente Cloud
Todo lo demás que hace la API tiene un cliente: sesiones, ejecuciones de agente, perfiles y webhooks. Lee CLEARCOTE_API_KEY y CLEARCOTE_API_URL, o los recibe como argumentos. El cliente de Python usa solo la biblioteca estándar; AsyncCloud tiene los mismos métodos para 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étodos |
|---|---|
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) |
Cada método devuelve el JSON del endpoint tal cual: un dict en Python, un objeto simple en Node. Las llamadas de lista devuelven el objeto de la API, por ejemplo { balanceEur, sessions } o { runs }, no una lista sin más. Los tiempos que espera el propio SDK (timeout, poll) van en segundos en ambos lenguajes.
Node tiene los mismos métodos en camelCase (handoffDone, waitHandoff, importCookies, recordingUrl, downloadRecording), con los argumentos opcionales en un objeto: live(id, { control }), events(id, { after, limit }), runs.create(task, { url, schema, country, … }), importCookies(name, cookies, { mode }), webhooks.create(url, { events }). Una llamada fallida lanza CloudError con el status HTTP (0 cuando no se pudo llegar a la API), el code de la API y su message; los códigos están en Errores. Una espera que supera su timeout lanza en su lugar CloudTimeoutError, cuyo last contiene el último estado que leyó el SDK; la ejecución o el traspaso continúa en el servidor. Una opción incorrecta lanza ValueError en Python (un Error en Node) antes de enviar nada. El SDK también exporta verify_webhook / verifyWebhook para las firmas de webhook.
El comando clearcote cloud
El comando clearcote que viene con el SDK (pip install clearcote, o npx clearcote) tiene un grupo cloud para la misma 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>Todos los comandos aceptan --json para imprimir la respuesta de la API en lugar de un resumen. run espera el resultado y sale con 0 solo cuando la ejecución terminó en succeeded (1 en otro caso, 2 para un error de uso), así que sirve en un script de shell. Sin -o, recording guarda en <id>.mp4. Ejecuta clearcote cloud --help para ver todos los flags.
Cada comando tiene su propia página: ejecuciones, grabaciones y eventos, sincronización de perfiles y webhooks.
MCP: un navegador en la nube para tu asistente de IA
El servidor MCP tiene el mismo interruptor. Con CLEARCOTE_CLOUD=1 y CLEARCOTE_API_KEY en su env, el navegador compartido que manejan sus herramientas es un navegador en la nube. Con una clave de API definida, también obtiene una herramienta run_task que entrega una tarea completa a una ejecución de agente y devuelve el JSON del resultado.
{
"mcpServers": {
"clearcote": {
"command": "npx",
"args": ["-y", "clearcote-mcp"],
"env": { "CLEARCOTE_CLOUD": "1", "CLEARCOTE_API_KEY": "cc_live_..." }
}
}
}