Instalação

Instale o SDK e deixe que ele baixe um navegador verificado — ou baixe e verifique um build você mesmo.

O Clearcote está em desenvolvimento ativo. Há builds para Windows x64 e Linux x64 — o SDK baixa o certo para o seu sistema operacional. O macOS está no roadmap; até lá, quem usa macOS pode rodar a imagem Docker. Em um host Linux mínimo, instale as bibliotecas de runtime do navegador (libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libpango-1.0-0 …) — clearcote info lista as que estiverem faltando. Se você mesmo iniciar o binário como root (algo típico em contêineres), passe --no-sandbox; o SDK e o clearcote serve já cuidam disso para você.

Instale o SDK (recomendado)

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

O primeiro launch() baixa o navegador para o seu sistema operacional, confere o SHA-256 e o guarda em cache. Você não precisa rodar playwright install — cada SDK traz o próprio driver do Playwright e baixa o próprio navegador. O build que você recebe depende de haver ou não uma chave de licença definida:

Defina uma chave de licença

O SDK procura a chave nesta ordem: a opção de inicialização licenseKey / license_key / LicenseKey, depois a variável de ambiente CLEARCOTE_LICENSE_KEY e, por fim, ~/.clearcote/license.key — o arquivo que o clearcote login grava. Todos os SDKs, inclusive o .NET, leem esse arquivo. Pegue uma chave gratuita em “Licenses”, no seu painel.

clearcote login cc_lic_...              # checks the key, saves it to ~/.clearcote/license.key
export CLEARCOTE_LICENSE_KEY=cc_lic_...  # or per process / per container

O comando clearcote

Os pacotes de Python e de Node instalam um comando clearcote (com uma instalação local via npm, rode-o como npx clearcote …). O pacote .NET não inclui esse comando.

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

clearcote install --version 153 ou --channel preview escolhe um build específico; veja como escolher um build. Em seguida, integre-o ao Playwright ou Puppeteer.

Instalação manual (build aberto)

Prefere o binário puro? O GitHub Releases traz o build aberto. O build licenciado não é publicado lá: ele roda pelo SDK, pelo clearcote serve ou pela imagem Docker, e não inicia sem o token de execução que o SDK fornece.

1. Baixe

Baixe a versão v0.1.0-pre.* mais recente — atualmente v0.1.0-pre.22 (Chromium 149.0.7827.114). Cada versão inclui:

• clearcote-<version>-windows-x64.zip — o build para Windows (Chromium + runtime + DLLs do VC++)
• clearcote-<version>-linux-x64.tar.xz — o build para Linux
• Arquivos .sha256 e SHA256SUMS.txt — checksums
• Arquivos .asc + clearcote-signing-key.asc — assinaturas GPG destacadas e a chave pública

2. Verifique (recomendado)

O build aberto é feito para que você não precise confiar em nós. Antes de extrair, confirme que o download é exatamente o que foi compilado e assinado — veja Verificação.

3. Extraia

O arquivo para Windows é autossuficiente: as DLLs de runtime do VC++ 2015–2022 vêm incluídas, então ele roda em uma máquina Windows 10/11 limpa. O arquivo para Linux precisa das bibliotecas de runtime listadas acima.

Expand-Archive clearcote-149.0.7827.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. Smoke test

Inicie o navegador apontando para uma página de teste de fingerprint, com um seed:

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

Mesmo seed em --fingerprint ⇒ a mesma identidade a cada inicialização; um seed novo ⇒ uma identidade nova. Para reportar os valores capturados de uma máquina real em vez dos derivados do seed, importe um perfil capturado — veja Flags de fingerprint. Depois, integre-o ao Playwright ou Puppeteer.

Rode no Docker

A imagem oficial roda o Clearcote como um endpoint CDP — baixe a imagem e aponte qualquer cliente Playwright, Puppeteer ou browser-use para ela pelo Chrome DevTools Protocol, sem mudar o 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")

Configure a persona com variáveis de ambiente — CC_PLATFORM (windows/linux/macos/android), CC_FINGERPRINT (seed), CC_BRAND (Edge…), CC_ACCEPT_LANGUAGE, CC_TIMEZONE, CC_TLS_PROFILE. Defina CC_FINGERPRINT para cada identidade: sem ela, todos os contêineres compartilham o mesmo seed padrão. A imagem traz o build aberto; adicione -e CLEARCOTE_LICENSE_KEY=cc_lic_… -v clearcote-cache:/opt/xdg-cache para rodar o build licenciado mais recente, baixado uma única vez para o volume. O navegador roda em modo headed, em um display virtual (CC_HEADLESS=1 para headless puro), e a imagem é linux/amd64. O Dockerfile é auditável — faça o build você mesmo. O endpoint CDP dá controle total do navegador, então publique-o apenas em redes confiáveis (-p 127.0.0.1:9222:9222 o mantém restrito ao host). Mais em Deploy.

Requisitos

• Windows 10 / 11 x64, ou Linux x64 (glibc) com as bibliotecas de runtime acima.
• No Windows, não é preciso instalar o VC++ redistributable à parte — ele já vem incluído no arquivo.
• SDK: Node 20+, Python 3.8+ ou .NET 8. Cada um traz o próprio driver do Playwright (playwright-core, playwright, Microsoft.Playwright).
• Se você usa o binário do build aberto diretamente: a sua instalação atual do Playwright ou do Puppeteer (o Clearcote substitui o navegador, não o driver).