Instalación

Instala el SDK y deja que descargue un navegador verificado, o descarga y verifica un build por tu cuenta.

Clearcote está en desarrollo activo. Hay builds para Windows x64 y Linux x64, y el SDK descarga el que corresponde a tu sistema operativo. En una Mac con Apple Silicon, el navegador se ejecuta de forma nativa (el build con licencia como versión preliminar, o el build abierto de 150 sin clave de licencia); en una Mac con Intel, launch() ejecuta por ti la imagen de Docker de Clearcote (consulta macOS). En un host Linux mínimo, instala las bibliotecas de runtime del navegador (libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libpango-1.0-0 …); clearcote info indica las que faltan. Si inicias el binario tú mismo como root (lo habitual en contenedores), pasa --no-sandbox; el SDK y clearcote serve se encargan de eso por ti.

Instala el SDK (recomendado)

npm i clearcote                # Node 20+
pip install clearcote          # Python 3.8+
dotnet add package Clearcote   # .NET 8

El primer launch() descarga el navegador para tu sistema operativo, comprueba su SHA-256 y lo guarda en caché. No hace falta ejecutar playwright install: cada SDK trae su driver de Playwright y descarga su propio navegador. El build que obtienes depende de si hay una clave de licencia configurada:

Configura una clave de licencia

El SDK busca la clave en este orden: la opción de lanzamiento licenseKey / license_key / LicenseKey, luego la variable de entorno CLEARCOTE_LICENSE_KEY y, por último, ~/.clearcote/license.key, el archivo que escribe clearcote login. Todos los SDK, incluido el de .NET, leen ese archivo. Consigue una clave gratis en “Licenses”, en tu panel.

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

Inicia sesión desde otro dispositivo

clearcote login --device (SDK 0.40.0+, Python y Node; npx clearcote login --device con una instalación local de npm) guarda una clave sin que tengas que copiarla. Muestra un enlace y un código corto. Abre el enlace en un navegador de cualquier dispositivo donde puedas iniciar sesión en clearcotelabs.com, comprueba que la página muestre el mismo código que tu terminal, marca la casilla que confirma que la terminal es tuya y aprueba. La página indica que el dispositivo ya inició sesión, y la terminal muestra Signed in as con la dirección de email de tu cuenta (parcialmente oculta), dónde guardó la clave, y el plan y su vencimiento. La clave en sí nunca se muestra, ni en la página ni en la terminal.

Un código dura 10 minutos; después, vuelve a ejecutar el comando para obtener uno nuevo. Si presionas Ctrl-C mientras espera, no se guarda nada, y un segundo Ctrl-C lo detiene al instante. Usa --device en un servidor al que accedes por SSH, en un contenedor o cuando un agente de programación configura Clearcote por ti: la aprobación ocurre en tu propio navegador y ningún secreto pasa por la terminal, su historial ni un chat. Si tienes la clave a mano en tu propia máquina, clearcote login funciona igual de bien: desde la 0.40.0 lee la clave sin mostrarla.

El comando clearcote

Los paquetes de Python y Node instalan un comando clearcote (con una instalación local de npm, ejecútalo como npx clearcote …). El paquete de .NET no incluye ninguno.

clearcote install              # download + verify the browser now (CI, Docker builds)
clearcote info                 # this machine, 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 bench --proxy <url>  # what each browser costs here in CPU and RAM, page timings, how many fit at once
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
clearcote connect [code]       # start the helper for the web Profile Manager — see below

Todos los comandos aceptan --help. Desde el SDK 0.40.0, clearcote info prueba el build que ejecutaría launch(), incluido el que indica CLEARCOTE_BROWSER_VERSION, y muestra cuándo vence la clave si se guardó con clearcote login --device (para una clave pegada, ningún servicio de licencias informa su vencimiento). Desde 0.41.0, en Linux, también indica qué sistemas de escritura pueden dibujar las fuentes que vería un lanzamiento (consulta tus propias fuentes en Linux). clearcote install --version 154 o --channel preview elige un build concreto; consulta cómo elegir un build. Después, intégralo con Playwright o Puppeteer.

Desde 0.56.0, clearcote info empieza por la propia máquina (procesador, memoria, sistema operativo, máquina virtual o contenedor, y si hay una tarjeta gráfica con la que el navegador pueda dibujar). clearcote bench inicia --concurrency navegadores (3 por defecto), carga --url durante --duration segundos (30 por defecto), a través de --proxy si lo indicas, e informa de lo que cuesta cada navegador en hilos de CPU y RAM en esta máquina, los tiempos de carga, los errores, cuántos navegadores aguanta la máquina a la vez, más o menos, y qué cambiar. Si la memoria libre parece escasa, inicia menos navegadores (--force los inicia todos), y cada navegador ocupa una plaza de la licencia mientras se ejecuta. Pega la salida en una solicitud de soporte. En .NET, ClearcoteBench.RunAsync y ClearcoteHost.Info dan el mismo informe desde el código.

Desde la 0.61.0, clearcote connect inicia el Clearcote Helper en esa terminal, para que la versión web del Profile Manager en app.clearcotelabs.com pueda abrir tus perfiles en este ordenador. En su ventana Connect, elige I use the Clearcote SDK y ejecuta el comando que muestra, con su código de un solo uso (npx clearcote connect 4F7-K2Q): esa pestaña se conecta sola, sin la página de aprobación. La primera vez descarga la versión del helper que fija el SDK y comprueba su SHA-256. Deja la terminal abierta; Ctrl+C cierra el helper y sus navegadores.

macOS

En una Mac con Apple Silicon (M1 o posterior, macOS 13 o posterior) con una clave de licencia, el SDK (0.51.1+) descarga el build con licencia para macOS y lo inicia de forma nativa, igual que en Windows y Linux. Es una versión preliminar y puede ir por detrás de Windows y Linux: ahora mismo es 155.0.8059.39-r49 mientras ellos ejecutan 156.0.8078.47-r57. Sin clave de licencia, el SDK (0.68.4+) descarga el build abierto de 150 para Apple Silicon (v0.1.0-pre.24, una versión de Chromium por detrás de los builds abiertos para Windows y Linux) y también lo inicia de forma nativa.

En una Mac con Intel (y, con el SDK 0.40.0 a 0.68.3, en cualquier Mac sin clave de licencia), launch() inicia la imagen de Docker de Clearcote (teamflatearth/clearcote:sdk-<SDK version>, una imagen linux/amd64 que Docker Desktop ejecuta en Intel y en Apple silicon), se conecta a ella y devuelve el mismo navegador de Playwright que un lanzamiento local. Tu código no cambia, y close() detiene y elimina el contenedor. Esto cubre launch() en Python (síncrono y asíncrono), Node y .NET (LaunchAsync); los demás puntos de entrada, como los contextos persistentes y serve(), siguen necesitando un binario de Clearcote, así que en un Mac ejecútalos directamente en la imagen de 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 debe estar instalado y en ejecución. Sin él, launch() falla con DockerUnavailableError (.NET: DockerUnavailableException) y un mensaje que indica qué hacer. El primer lanzamiento descarga la imagen y, con una clave de licencia, el build más reciente, una sola vez, en el volumen clearcote-cache; los lanzamientos siguientes arrancan en segundos.
• Qué se pasa al contenedor: las opciones de persona, headless, proxy, args, version y la clave de licencia (que se busca igual que en cualquier otra máquina, incluida la que guardó clearcote login). Una opción que el contenedor no admite se rechaza indicando su nombre. La clave y el proxy llegan al contenedor como un archivo que este lee una vez y luego borra, así que docker inspect no los muestra, y un lanzamiento con clave o con proxy se rechaza si el contenedor no ejecuta el build con licencia o no usa el proxy.
• No queda nada en ejecución. Si tu programa termina o se cierra a la fuerza sin close(), su contenedor se detiene solo unos 30 segundos después de que nada esté conectado a él, y el siguiente lanzamiento elimina los restos cuyo programa ya no existe. Nunca se tocan los contenedores que pertenecen a otros programas en ejecución, a otros usuarios o a otras máquinas. Desde el SDK 0.41.0, close() solo regresa cuando Docker ya eliminó el contenedor y su volumen, así que después docker ps -a ya no lo muestra.
• Chrome conserva su sandbox (SDK 0.41.0+ con una imagen a partir de sdk-0.41.0): el lanzamiento pasa el perfil seccomp de la imagen, así que Chrome se ejecuta con su sandbox dentro del contenedor (consulta el sandbox de Chrome). Eso requiere Docker en una CPU x86_64; en Apple silicon la imagen se ejecuta emulada y, por ahora, el sandbox queda desactivado.
• El contenedor ejecuta Linux, así que su persona por defecto es de Linux. Lee Despliegue antes de declarar otra plataforma desde un contenedor.

Cada imagen se publica unos minutos después de su versión del SDK, así que justo después de actualizar puede que el tag correspondiente todavía no exista; el error lo indica y, mientras tanto, CLEARCOTE_DOCKER_IMAGE puede apuntar a un tag anterior.

Instalación manual (build abierto)

¿Prefieres el binario sin más? En GitHub Releases está el build abierto. El build con licencia no se publica ahí: se ejecuta a través del SDK, de clearcote serve o de la imagen de Docker, y no arranca sin el token de ejecución que proporciona el SDK.

1. Descarga

Descarga la versión v0.1.0-pre.* más reciente; actualmente es v0.1.0-pre.25 (Chromium 151.0.7922.108). Cada versión incluye:

• clearcote-<version>-windows-x64.zip: el build para Windows (Chromium + runtime + DLLs de VC++)
• clearcote-<version>-linux-x64.tar.xz: el build para Linux
• archivos .sha256 y SHA256SUMS.txt: checksums
• archivos .asc + clearcote-signing-key.asc: firmas GPG separadas y la clave pública

2. Verifica (recomendado)

El build abierto está hecho para que no tengas que confiar en nosotros. Antes de extraerlo, confirma que la descarga es exactamente lo que se compiló y firmó; consulta Verificación.

3. Extrae

El archivo de Windows es autónomo: incluye las DLLs del runtime de VC++ 2015–2022, así que funciona en un Windows 10/11 recién instalado. El archivo de Linux necesita las bibliotecas de runtime indicadas arriba.

Expand-Archive clearcote-151.0.7922.108-windows-x64.zip -DestinationPath C:\clearcote

# you now have:
#   C:\clearcote\chrome.exe
#   C:\clearcote\chrome.dll  + runtime, locales, ICU, ANGLE, VC++ DLLs

4. Prueba de humo

Lánzalo con un seed contra una página de test de huella digital:

C:\clearcote\chrome.exe --fingerprint=seed-123 --fingerprint-platform=windows https://abrahamjuliot.github.io/creepjs/

Mismo seed de --fingerprint ⇒ la misma identidad en cada lanzamiento; un seed nuevo ⇒ una identidad nueva. Para reportar los valores capturados de una máquina real en lugar de los derivados del seed, importa un perfil capturado; consulta Flags de huella digital. Después, intégralo con Playwright o Puppeteer.

Ejecución en Docker

La imagen oficial ejecuta Clearcote como un endpoint CDP: descárgala y apunta cualquier cliente de Playwright, Puppeteer o browser-use hacia ella mediante el Chrome DevTools Protocol, sin cambiar el código.

# Chrome's sandbox profile, shipped in the image
docker run --rm --tmpfs /opt/xdg-cache --entrypoint cat teamflatearth/clearcote /etc/clearcote/seccomp.json > clearcote-seccomp.json
docker run -d --rm --shm-size=1g -p 127.0.0.1:9222:9222 --security-opt seccomp=clearcote-seccomp.json -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")

Configura la persona con variables de entorno: CC_PLATFORM (windows/linux/macos/android), CC_FINGERPRINT (seed), CC_BRAND (Edge…), CC_ACCEPT_LANGUAGE, CC_TIMEZONE, CC_TLS_PROFILE. Sin CC_FINGERPRINT, cada contenedor recibe su propio seed aleatorio, que se conserva entre reinicios; defínela para elegir o reutilizar una identidad. La imagen incluye el build abierto; agrega -e CLEARCOTE_LICENSE_KEY=cc_lic_… -v clearcote-cache:/opt/xdg-cache para ejecutar el build con licencia más reciente, que se descarga una sola vez en el volumen. El navegador se ejecuta en modo headed sobre una pantalla virtual (CC_HEADLESS=1 para headless puro) y la imagen es linux/amd64. El Dockerfile se puede auditar: recompílalo tú mismo. El endpoint CDP da control total del navegador, así que publícalo solo en redes de confianza (-p 127.0.0.1:9222:9222 lo mantiene local al host). Más información en Despliegue.

Límites de descarga

Las descargas de la versión con licencia tienen un límite por licencia, para que una configuración que baja el archivo completo en cada inicio no se descontrole. Un inicio que encuentra la versión en su caché no descarga nada y nunca cuenta: solo cuentan las descargas reales.

Por encima de un límite, el SDK recibe HTTP 429 con un cuerpo JSON (code es DOWNLOAD_RATE_LIMITED (cupo por versión) o DOWNLOAD_LIMIT_EXCEEDED (plan gratuito)) y una cabecera Retry-After: los segundos que faltan para que se reinicie el límite. Los inicios cuya versión ya está en caché siguen funcionando. Desde el SDK 0.62.0, un inicio que no puede descargar una versión nueva arranca, en lugar de fallar, la versión más reciente de la misma versión de Chromium que ya tiene en caché, y espera aRetry-After antes de volver a intentar esa descarga. Un inicio fijado a una revisión exacta (r50) sigue recibiendo esa versión o un error.

Llegas a estos límites cuando muchas máquinas o contenedores nuevos arrancan a la vez, cada uno con la caché vacía. Descarga cada versión una vez por máquina en lugar de una vez por inicio; además arrancan más rápido, sin una descarga de unos 460 MB:

• Guarda la caché en un volumen. Apunta CLEARCOTE_CACHE a un directorio que sobreviva a los reinicios. Los inicios que lo comparten esperan a la primera descarga y la reutilizan.
• Incluye el navegador en tu imagen. Ejecuta clearcote install al construirla, para que cada contenedor arranque con la versión ya instalada. Reconstruye la imagen cuando actualices.

# 1. a shared, persistent cache
docker run -v clearcote-cache:/clearcote-cache -e CLEARCOTE_CACHE=/clearcote-cache …

# 2. or in your Dockerfile: download once while the image is built (the key stays out of the layers)
ENV CLEARCOTE_CACHE=/opt/clearcote-cache
RUN --mount=type=secret,id=clearcote_key \
    CLEARCOTE_LICENSE_KEY="$(cat /run/secrets/clearcote_key)" clearcote install

Límites de personas

Cada inicio obtiene su persona (la huella digital que describen ese seed y esas opciones) del servicio de personas. Cada licencia puede obtener una cantidad fija de personas distintas por día. Obtener una persona que ya usaste hoy no cuesta nada, así que un conjunto fijo de perfiles puede volver a iniciarse tantas veces como quieras.

Una persona es un seed con un conjunto de opciones de huella digital (marca, plataforma, etc.), así que el mismo seed como Chrome y como Edge cuenta dos veces. El conteo se reinicia a las 00:00 UTC. Al superar el límite, el inicio falla con HTTP 429 del servicio de personas (daily persona quota reached) hasta el reinicio.

Esto te pasa cuando cada inicio usa un seed aleatorio totalmente nuevo. En su lugar, reutiliza un grupo fijo de seeds, por ejemplo una lista de unos cientos de nombres que vas rotando: cada uno conserva la misma huella digital cada vez que arranca, y volver a iniciarlo nunca cuenta de nuevo.

Requisitos

• Windows 10 / 11 x64, o Linux x64 (glibc) con las bibliotecas de runtime indicadas arriba.
• macOS: en Apple Silicon (macOS 13+), nada adicional (SDK 0.51.1+ con clave de licencia, 0.68.4+ sin ella). En una Mac con Intel, Docker Desktop en ejecución, para launch() (SDK 0.40.0+).
• En Windows no hace falta instalar aparte el redistribuible de VC++: viene incluido en el archivo.
• SDK: Node 20+, Python 3.8+ o .NET 8. Cada uno instala su propio driver de Playwright (playwright-core, playwright, Microsoft.Playwright).
• Si usas directamente el binario del build abierto: tu instalación actual de Playwright o Puppeteer (Clearcote reemplaza el navegador, no el driver).