Saltar al contenido

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 session
Esta pestaña se ejecuta en tu máquina.

Detrá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.

VariableSignificado
CLEARCOTE_CLOUD1, true o yes: un launch() sin argumento cloud inicia un navegador en la nube. Cualquier otro valor, o sin definir: uno local.
CLEARCOTE_API_KEYTu clave cc_live_…. Necesaria para cada llamada a la nube.
CLEARCOTE_API_URLLa 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.
bash
export CLEARCOTE_API_KEY=cc_live_...

python scrape.py                     # a local browser
CLEARCOTE_CLOUD=1 python scrape.py   # the same script on a hosted browser

Un 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.

PythonNode y APISignificado
identityidentityUna etiqueta por cuenta: el mismo dispositivo y la misma IP residencial mientras esa IP siga en línea.
fingerprintfingerprintSeed del dispositivo. El mismo seed da el mismo perfil de dispositivo.
light_stealthlightStealthPor defecto true.
platformplatformwindows, macos, linux o android.
brandbrandChrome, Edge, Opera o Vivaldi.
timezonetimezoneNombre IANA, por ejemplo Europe/Berlin.
locale, accept_languagelocaleAccept-Language, por ejemplo de-DE,de. accept_language (Node: acceptLanguage) es un alias.
geoIdentitygeoIdentityDefault "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.
geoipgeoipLa zona horaria y el idioma siguen a la IP de salida.
proxyproxy"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.
countrycountryPaís de salida en el pool residencial gestionado.
statestateEstado o región de salida en el pool gestionado. Requiere country.
citycityCiudad de salida en el pool gestionado. Requiere state.
proxy_sessionproxySessionEtiqueta sticky: la misma etiqueta recupera más tarde la misma IP de salida.
timeout_sectimeoutSecLímite estricto de duración de la sesión, en segundos.
idle_timeout_secidleTimeoutSecTermina la sesión tras este tiempo sin ningún comando CDP.
max_gbmaxGbDetiene la sesión tras esta cantidad de tráfico.
headlessheadlessPor 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.
humanizehumanizeDefault 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_alivekeepAliveMantiene el navegador en ejecución después de que te desconectas.
versionversionEjecuta una versión concreta de Clearcote.
profileprofileUn perfil en la nube: "name" para cargarlo, { name, persist: true } para además guardarlo de vuelta.
urlurlSe abre en la primera pestaña antes de que recibas el navegador.
adblockadblockRechaza hosts conocidos de anuncios y rastreadores antes de que carguen.
solve_sliderssolveSlidersPor 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_checkboxessolveCheckboxesPor 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_holdsolvePressHoldPor 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_servicechallengeServiceDesactivado 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.
recordrecordGraba un MP4 de la sesión.
notenoteTu etiqueta para la sesión.
workerworkerInicia en el mismo servidor que una sesión anterior.
humanizehumanizeSin 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_cursorshowCursorMuestra un punto rojo que sigue al mouse, para observar o depurar. Del lado del SDK, como humanize.
api_key, api_urlapiKey, apiUrlLa 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_motimeout, slowMoLas 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 un Browser y launch_persistent_context() un BrowserContext, 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; pasa humanize=False para 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 version fija el mismo build.

Diferente:

  • Las opciones solo locales se rechazan. executable_path, args, user_data_dir, extensions, ignore_default_args y las demás opciones que solo tienen sentido para un binario en tu máquina lanzan ValueError("<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).
  • profile significa un perfil en la nube. En local, profile elige 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, lightStealth activado, 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 propio proxy.
  • 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. Con keep_alive / keepAlive el 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) y page.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"
Esta pestaña se ejecuta en tu máquina.

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)
Esta pestaña se ejecuta en tu máquina.
NamespaceMétodos
browserscreate(**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)
runscreate(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)
profileslist(), get(name), delete(name), import_cookies(name, cookies, mode="merge"), sync(name, …)
webhookscreate(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:

bash
# 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.

json
{
  "mcpServers": {
    "clearcote": {
      "command": "npx",
      "args": ["-y", "clearcote-mcp"],
      "env": { "CLEARCOTE_CLOUD": "1", "CLEARCOTE_API_KEY": "cc_live_..." }
    }
  }
}

Actualizado el 18 oct 2026 · SDK 0.70.5 · navegador r63

¿Te resultó útil esta página?