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. Em um Mac com Apple Silicon, o navegador roda nativamente (o build licenciado como preview, ou o build aberto 150 sem chave de licença); em um Mac Intel, o launch() roda a imagem Docker do Clearcote para você (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                 # 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

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.

A partir da 0.56.0, clearcote info começa pela própria máquina (processador, memória, sistema operacional, máquina virtual ou contêiner, e se há uma placa de vídeo com a qual o navegador possa desenhar). clearcote bench inicia --concurrency navegadores (3 por padrão), carrega --url por --duration segundos (30 por padrão), pelo --proxy se você informar um, e relata quanto cada navegador custa em threads de CPU e RAM nesta máquina, os tempos de carregamento, os erros, quantos navegadores a máquina roda ao mesmo tempo, aproximadamente, e o que mudar. Quando a memória livre parece pouca, ele inicia menos navegadores (--force inicia todos), e cada navegador ocupa uma vaga da licença enquanto roda. Cole a saída em um pedido de suporte. No .NET, ClearcoteBench.RunAsync e ClearcoteHost.Info dão o mesmo relatório pelo código.

A partir da 0.61.0, clearcote connect inicia o Clearcote Helper nesse terminal, para que a versão web do Profile Manager em app.clearcotelabs.com possa abrir seus perfis neste computador. Na janela Connect, escolha I use the Clearcote SDK e rode o comando mostrado, com o código de uso único (npx clearcote connect 4F7-K2Q): essa aba se conecta sozinha, sem a página de aprovação. Na primeira vez, o SDK baixa a versão do helper que ele fixa e confere o SHA-256. Deixe o terminal aberto; Ctrl+C fecha o helper e os navegadores dele.

macOS

Em um Mac com Apple Silicon (M1 ou mais recente, macOS 13 ou posterior) com uma chave de licença, o SDK (0.51.1+) baixa o build licenciado para macOS e o inicia nativamente, como no Windows e no Linux. É um preview e pode ficar atrás do Windows e do Linux: no momento é 155.0.8059.39-r49, enquanto eles rodam 156.0.8078.47-r57. Sem chave de licença, o SDK (0.68.4+) baixa o build aberto 150 para Apple Silicon (v0.1.0-pre.24, uma versão do Chromium atrás dos builds abertos para Windows e Linux) e também o inicia nativamente.

Em um Mac Intel (e, com o SDK 0.40.0 a 0.68.3, em qualquer Mac sem chave de licença), o launch() 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.25 (Chromium 151.0.7922.108). 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-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. 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.

# 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")

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.

Limites de download

Os downloads da versão licenciada têm limite por licença, para que uma configuração que baixa o arquivo completo a cada início não saia do controle. Um início que encontra a versão no cache não baixa nada e nunca conta: só downloads reais contam.

Acima de um limite, o SDK recebe HTTP 429 com um corpo JSON (code é DOWNLOAD_RATE_LIMITED (cota por versão) ou DOWNLOAD_LIMIT_EXCEEDED (plano gratuito)) e um cabeçalho Retry-After: os segundos até o limite ser reiniciado. Inícios cuja versão já está no cache continuam funcionando. A partir do SDK 0.62.0, um início que não consegue baixar uma versão nova abre, em vez de falhar, a versão mais recente da mesma versão do Chromium que já está no cache, e espera o Retry-After antes de tentar esse download de novo. Um início fixado em uma revisão exata (r50) continua recebendo essa versão ou um erro.

Você atinge esses limites quando muitas máquinas ou contêineres novos sobem ao mesmo tempo, cada um com o cache vazio. Baixe cada versão uma vez por máquina em vez de uma vez por início: os inícios também ficam mais rápidos, sem um download de cerca de 460 MB:

• Mantenha o cache em um volume. Aponte CLEARCOTE_CACHE para um diretório que sobreviva a reinícios. Inícios que o compartilham esperam o primeiro download e o reaproveitam.
• Coloque o navegador na sua imagem. Rode clearcote install no build, para que todo contêiner já comece com a versão no lugar. Refaça a imagem quando atualizar.

# 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

Limites de personas

Cada inicialização busca a sua persona (o fingerprint que a seed e as opções descrevem) no serviço de personas. Cada licença pode buscar um número fixo de personas diferentes por dia. Buscar uma persona que você já usou hoje não custa nada, então um conjunto fixo de perfis pode ser reiniciado quantas vezes você quiser.

Uma persona é uma seed com um conjunto de opções de fingerprint (marca, plataforma etc.), então a mesma seed como Chrome e como Edge conta duas vezes. A contagem é reiniciada às 00:00 UTC. Acima do limite, a inicialização falha com HTTP 429 do serviço de personas (daily persona quota reached) até a reinicialização.

Isso acontece quando cada inicialização usa uma seed aleatória nova. Em vez disso, reutilize um conjunto fixo de seeds, por exemplo uma lista de algumas centenas de nomes que você vai alternando: cada um mantém o mesmo fingerprint toda vez que inicia, e reiniciá-lo nunca conta de novo.

Requisitos

• Windows 10 / 11 x64, ou Linux x64 (glibc) com as bibliotecas de runtime acima.
• macOS: no Apple Silicon (macOS 13+), nada a mais (SDK 0.51.1+ com chave de licença, 0.68.4+ sem). Em um Mac Intel, 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).