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. No hay un build nativo para macOS: en macOS, launch() ejecuta por ti la imagen de Docker de Clearcote (SDK 0.40.0+, 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                 # 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 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

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.

macOS

No hay un build nativo para macOS. Desde el SDK 0.40.0, launch() en macOS 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.23 (Chromium 150.0.7871.114). 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-150.0.7871.114-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.

docker run -d --rm -p 127.0.0.1:9222:9222 -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.

Requisitos

• Windows 10 / 11 x64, o Linux x64 (glibc) con las bibliotecas de runtime indicadas arriba.
• macOS (Intel o Apple silicon): 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).