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. Não existe build nativo para macOS: no macOS, o launch() roda a imagem Docker do Clearcote para você (SDK 0.40.0+, veja macOS). 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 --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

Faça login de outro dispositivo

O clearcote login --device (SDK 0.40.0+, Python e Node; npx clearcote login --device com uma instalação local via npm) salva uma chave sem que você precise copiar nenhuma. Ele mostra um link e um código curto. Abra o link num navegador, em qualquer dispositivo em que você consiga entrar no clearcotelabs.com, confira se a página mostra o mesmo código que o seu terminal, marque a caixa que confirma que o terminal é seu e aprove. A página informa que o dispositivo está conectado, e o terminal mostra Signed in as com o endereço de e-mail da sua conta (parcialmente oculto), o local onde a chave foi salva, o plano e a validade. A chave em si nunca é exibida, nem na página nem no terminal.

Um código vale por 10 minutos; depois disso, rode o comando de novo para receber outro. Um Ctrl-C durante a espera não salva nada, e um segundo Ctrl-C encerra na hora. Use --device num servidor que você acessa por SSH, num contêiner ou quando um agente de programação configura o Clearcote para você: a aprovação acontece no seu próprio navegador, e nada secreto passa pelo terminal, pelo histórico dele ou por um chat. Com a chave à mão na sua própria máquina, o clearcote login funciona igualmente bem: desde a 0.40.0, ele lê a chave sem exibi-la.

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

Todo comando aceita --help. A partir do SDK 0.40.0, o clearcote info testa o build que o launch() rodaria, inclusive o que a CLEARCOTE_BROWSER_VERSION indicar, e mostra quando a chave expira se ela foi salva com clearcote login --device (nenhum serviço de licença informa a validade de uma chave colada). A partir da 0.41.0, no Linux, ele também informa quais sistemas de escrita as fontes que uma inicialização enxergaria conseguem desenhar (veja suas próprias fontes no Linux). clearcote install --version 154 ou --channel preview escolhe um build específico; veja como escolher um build. Em seguida, integre-o ao Playwright ou Puppeteer.

macOS

Não existe build nativo para macOS. A partir do SDK 0.40.0, o launch() no macOS inicia a imagem Docker do Clearcote (teamflatearth/clearcote:sdk-<SDK version>, uma imagem linux/amd64 que o Docker Desktop roda em Intel e em Apple silicon), se conecta a ela e retorna o mesmo navegador Playwright que uma inicialização local retorna. O seu código não muda, e o close() para e remove o contêiner. Isso vale para o launch() em Python (síncrono e assíncrono), Node e .NET (LaunchAsync); os outros pontos de entrada, como contextos persistentes e o serve(), ainda precisam de um binário do Clearcote, então, num Mac, rode-os diretamente na imagem 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

• O Docker Desktop precisa estar instalado e rodando. Sem ele, o launch() lança DockerUnavailableError (.NET: DockerUnavailableException) dizendo o que fazer. A primeira inicialização baixa a imagem e, com uma chave de licença, o build mais recente, uma única vez, para o volume clearcote-cache; as inicializações seguintes começam em segundos.
• O que vai para o contêiner: as opções de persona, headless, proxy, args, version e a chave de licença (encontrada como em qualquer outra máquina, inclusive a que o clearcote login salvou). Uma opção que o contêiner não aceita é recusada, e o erro diz qual é. A chave e o proxy chegam ao contêiner num arquivo que ele lê uma vez e apaga, então o docker inspect não os mostra, e uma inicialização com chave ou proxy é recusada se o contêiner não rodar o build licenciado ou não usar o proxy.
• Nada fica rodando. Se o seu programa terminar ou for encerrado à força sem close(), o contêiner dele para sozinho cerca de 30 segundos depois que nada mais estiver conectado a ele, e a próxima inicialização remove as sobras cujo programa já não existe. Contêineres que pertencem a outros programas em execução, a outros usuários ou a outras máquinas nunca são tocados. Desde o SDK 0.41.0, o close() só retorna depois que o Docker remove o contêiner e o volume dele, então o docker ps -a deixa de listá-lo em seguida.
• O Chrome mantém o sandbox (SDK 0.41.0+ com uma imagem a partir da sdk-0.41.0): a inicialização passa o perfil seccomp da imagem, então o Chrome roda com o sandbox dentro do contêiner (veja O sandbox do Chrome). Isso exige o Docker numa CPU x86_64; no Apple silicon, a imagem roda emulada e o sandbox fica desligado por enquanto.
• O contêiner roda Linux, então a persona padrão dele é Linux. Leia Deploy antes de declarar outra plataforma a partir de um contêiner.

Cada imagem é publicada alguns minutos depois da versão do SDK correspondente, então, logo após um upgrade, a tag equivalente pode ainda não existir; o erro avisa isso, e a CLEARCOTE_DOCKER_IMAGE pode apontar para uma tag anterior enquanto isso.

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.23 (Chromium 150.0.7871.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-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. 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. Sem CC_FINGERPRINT, cada contêiner recebe o seu próprio seed aleatório, mantido entre reinicializações; defina a variável para escolher ou reutilizar uma identidade. 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.
• macOS (Intel ou Apple silicon): Docker Desktop rodando, para o launch() (SDK 0.40.0+).
• 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).