Mantendo o Clearcote atualizado

Sem chave de licença, cada versão do SDK fica fixada em um build aberto com SHA-256 verificado, e atualizar é só subir a versão do pacote, como de costume. Com uma chave, o SDK busca o build licenciado atual a cada inicialização — sem precisar subir versão nenhuma.

Quais builds estão disponíveis

As versões major do Chromium que distribuímos hoje ou nas quais estamos trabalhando, e quando cada plano recebe cada uma:

Usuários do SDK (recomendado)

Atualize o pacote do mesmo jeito que você atualiza qualquer dependência:

npm i clearcote@latest          # Node
pip install -U clearcote        # Python
dotnet add package Clearcote    # .NET (adds or updates to the newest version)

No próximo launch(), o SDK percebe que o build de que precisa não está em cache, faz o download — o build aberto do GitHub Releases, o build licenciado do clearcotelabs.com — e verifica o SHA-256 antes de usar. Nada roda sem verificação. Cada build fica em cache separadamente, no diretório de cache do usuário — %LOCALAPPDATA%\clearcote\Cache no Windows, ~/.cache/clearcote no Linux (defina CLEARCOTE_CACHE para mudar o local) —, então cada um é baixado uma única vez. Builds antigos ficam guardados até você rodar clearcote clear-cache.

Vários programas, um só cache

Programas que compartilham o cache se revezam para instalar um build (SDK 0.41.0+, em Python, Node e .NET): o primeiro faz o download, os outros esperam e depois o usam, e um build que outro programa está rodando nunca é substituído por baixo dele. Um programa que espera desiste depois de 30 minutos, com uma mensagem que indica o processo que está segurando a instalação (a trava é o arquivo .install-lock na pasta de cache daquele build; a mensagem diz quando é seguro apagá-lo). Uma trava deixada para trás por um programa que travou é assumida automaticamente.

Um build em cache cujos arquivos foram danificados ou removidos (uma quarentena do antivírus, uma pasta apagada) é reparado na próxima inicialização, com um único download. Se os arquivos dele ainda estiverem em uso, a inicialização para na hora e pede que você feche todos os programas que usam esse navegador e tente de novo. A trava exige que todos os processos que compartilham o cache rodem o SDK 0.41.0 ou mais recente; versões mais antigas não esperam por ela.

Windows: algumas configurações não conseguem iniciar um build baixado no lugar onde ele está, por exemplo um programa rodando dentro de um app empacotado (MSIX), cujas gravações em %LOCALAPPDATA% o Windows redireciona (a inicialização falha com spawn UNKNOWN ou "the side-by-side configuration is incorrect"). Nesse caso, o SDK faz uma cópia do build em ~/.clearcote/recovered, e todas as inicializações seguintes, do Python, do Node ou do .NET, usam essa cópia, então nada fica para trás na pasta temporária e as inicializações repetidas começam em segundos (Python e Node a partir da 0.40.1, .NET a partir da 0.41.0). O clearcote clear-cache também remove essas cópias; o SDK .NET não tem linha de comando, então chame WinLaunch.ClearRecovered() nele.

Atualizar o build aberto sem atualizar o SDK

Sem chave, ative a atualização automática para usar o build aberto mais recente do GitHub em vez do build fixado pelo SDK. Ele é verificado contra o SHA256SUMS.txt daquela versão (e contra a chave de assinatura quando o gpg está instalado); se o GitHub estiver inacessível, o SDK volta para o build fixado. Pelo terminal, clearcote update faz o mesmo. Com uma chave, isso não muda nada — você já recebe o build licenciado atual.

import { launch } from "clearcote";
await launch({ autoUpdate: true });   // or set env CLEARCOTE_AUTO_UPDATE=1

O navegador em si nunca “liga para casa” nem se atualiza sozinho. Sem chave, o navegador só muda quando você sobe a versão do SDK ou ativa o autoUpdate. Com uma chave, o SDK pega cada novo build licenciado na próxima inicialização; no Pro, dá para manter um build fixo com version.

Escolhendo um build

Passe version (ou defina CLEARCOTE_BROWSER_VERSION): "latest", uma major como "154", uma versão exata "154.0.8037.57" ou uma revisão licenciada "r36" / "154.0.8037.57-r36". Uma versão ou major é conferida no catálogo publicado, e uma revisão, no servidor de licenças, antes de qualquer download. releaseChannel: "preview" (release_channel em Python, ou CLEARCOTE_RELEASE_CHANNEL=preview) pega um build de preview quando houver um. No build licenciado, builds mais antigos, fixação de versão e o canal de preview são recursos do Pro — chaves gratuitas sempre recebem o mais recente.

clearcote install --version 154        # fetch + verify a build ahead of time
clearcote install --channel preview     # the newest preview build (Pro)
clearcote info                          # what's installed and cached, and your key
clearcote clear-cache                   # delete cached builds

Usuários do binário direto / Docker

• Binário direto (só o build aberto — o build licenciado roda pelo SDK, pelo clearcote serve ou pela imagem Docker): baixe o novo arquivo compactado na página de Releases, verifique o checksum + a assinatura (veja Verificação) e aponte executable_path / executablePath (ou CLEARCOTE_BINARY) para o novo chrome.
• Docker: docker pull teamflatearth/clearcote para pegar a imagem mais recente e, depois, recrie o seu contêiner. Chaves gratuitas precisam de uma imagem gerada a partir do SDK 0.30.0 ou mais recente. Com uma chave, monte -v clearcote-cache:/opt/xdg-cache para que o build licenciado seja baixado uma vez só, e não em cada contêiner novo. Veja Deploy.

O build licenciado — sempre atual, e primeiro

O build licenciado acompanha o Chromium mais recente e os patches mais novos, então você recebe as atualizações sem recompilar nada manualmente. Defina CLEARCOTE_LICENSE_KEY, passe licenseKey ou rode clearcote login (Python/Node; npx clearcote login em uma instalação local do npm) — ele valida a chave e a salva em ~/.clearcote/license.key, que todos os SDKs leem, inclusive o .NET. Há duas formas de conseguir uma chave:

• Grátis com GitHub — um navegador por vez, sem custo. Entre com uma conta do GitHub que tenha pelo menos 30 dias, abra Licenses no seu painel, clique em Connect GitHub and get it free e depois em Claim my free key (uma por conta do GitHub). A chave vale por 30 dias; renove-a de graça na mesma página antes que ela expire.
• Pro — o mesmo build, com até 250 navegadores simultâneos, builds mais antigos, fixação de versão e o canal de preview, além de suporte por e-mail com o próprio dono.

Novas majors chegam primeiro ao build licenciado. Quando uma nova major do Chromium é compilada, ela fica disponível no Grátis com GitHub e no Pro imediatamente; o build aberto recebe essa major depois — a meta é cerca de 2 meses após o lançamento (hoje ele está no Chromium 150). O build aberto é sempre totalmente aberto e reproduzível; o build licenciado recebe a major mais nova antes.

Como os navegadores licenciados são contados

Cada navegador iniciado com uma chave ocupa um slot no servidor de licenças e o devolve quando é fechado. O seu painel mostra quantos estão em uso, e clearcote info exibe a mesma contagem.

• O Grátis com GitHub conta cada navegador. É um slot só, então um segundo navegador — no mesmo programa, em outro programa ou em outra máquina — é recusado com The free tier runs one browser at a time, and one is already running até o primeiro ser fechado. Um navegador que travou sem fechar libera o slot em até 6 minutos.
• O Pro conta máquinas e cobre até 250 navegadores ao mesmo tempo. Todos os navegadores de uma máquina compartilham o slot dessa máquina. Assinaturas iniciadas antes de 26 de setembro de 2026 mantêm as condições anteriores, sem limite; se você precisar de mais de 250, peça e nós aumentamos.
• Chaves gratuitas exigem o SDK 0.30.0 ou mais recente (Python, Node e .NET), porque contar cada navegador exige que o SDK informe cada inicialização e mantenha a licença válida enquanto aquele navegador roda. Um SDK mais antigo recebe SDK_UPGRADE_REQUIRED com o comando de atualização, e um SDK mais antigo que chegue ao motor mesmo assim é recusado ali. Chaves Pro continuam funcionando com SDKs mais antigos, como antes.
• Um navegador gratuito é encerrado quando perde o slot. A verificação é contínua, não só na inicialização: se a chave for revogada, se o slot for devolvido em outro lugar ou se a licença passar do limite, um navegador gratuito que já esteja aberto é encerrado em cerca de 2 a 3 minutos. Quedas curtas de rede (um ou dois heartbeats perdidos) são toleradas; uma interrupção de mais de cerca de 2 a 3 minutos encerra um navegador gratuito da mesma forma.
• O plano gratuito sempre roda o build mais recente. Pedir um build licenciado mais antigo ou o canal de preview retorna FREE_LATEST_ONLY; fixar um build é recurso do Pro.
• Downloads com uma chave gratuita: até 10 builds diferentes a cada 24 horas. O mesmo build conta uma vez só, não importa quantas vezes você o inicie.

pip install -U clearcote          # Python 0.30.0+
npm i clearcote@latest            # Node 0.30.0+
dotnet add package Clearcote      # .NET 0.30.0+

O que muda quando você atualiza

A maioria das versões do SDK não muda nada que exija ação sua. Estas mudam o que uma configuração existente faz; todas as versões estão listadas em Releases, no seu painel.

• Build licenciado 154 r36, uma seed existente: agora uma seed tira a placa de vídeo de uma gama de modelos reais do próprio fabricante de GPU da máquina, em vez de um único modelo por fabricante, então a maioria das seeds reporta uma placa diferente da que reportava no r35. Numa máquina com placa NVIDIA, uma seed que declarava hardware de entrada (4 a 6 threads de processador, 4 a 8 GB de memória, uma tela pequena) agora declara hardware intermediário ou melhor, e nenhuma seed declara tela sensível ao toque numa máquina assim. Para manter as identidades que as suas seeds tinham antes do r36, defina persona_schema=2 / personaSchema: 2. Veja a mesma seed em máquinas diferentes.
• Build licenciado 154 r36, cookies de terceiros: o navegador agora os permite por padrão, como o Chrome faz, inclusive quando um SDK mais antigo ou o seu próprio launcher não passa nenhuma opção de cookies. --block-third-party-cookies os bloqueia.
• 0.42.0, hosts Linux: o WebGL de uma persona Linux agora renderiza pelo Mesa sobre EGL tanto em modo headed quanto headless (o host precisa de libegl1), então a string de renderer, a lista de extensões e os limites do WebGL de uma persona Linux em modo headed mudam uma vez, para a forma que as inicializações headless já mostravam e que a maioria das máquinas Linux reais reporta. Uma inicialização em modo headed sob Xvfb sem gerenciador de janelas abre ajustada à tela. As inicializações headless mantêm um display realista mesmo quando uma persona não tem efeito, e o serve() o mantém quando você passa só --window-position. Veja Playwright & Puppeteer.
• Build licenciado a partir do 154 r34, disableGpuFingerprint: agora muda só o que a GPU reporta. A leitura de pixels do WebGL mantém o ruído por site do seed, então readPixels e as exportações de um canvas WebGL concordam. Antes, ele desligava só o ruído do readPixels. Veja Flags de fingerprint.
• 0.41.1, entrada humanizada: com humanize, a rolagem anda em entalhes inteiros da roda do mouse, como uma roda de verdade: 100 px por entalhe numa identidade Windows, 120 no Linux e 40 no macOS. Uma distância pedida é arredondada para o entalhe mais próximo (no mínimo um), então mouse.wheel(0, 800) rola 800 px no Windows e 840 no Linux. A digitação agora às vezes pressiona a próxima tecla antes de soltar a anterior em pares rápidos. No .NET, um humanizer com um seed numérico agora se move com a mesma identidade motora que no Python e no Node; antes, todos os seeds numéricos diferentes de zero compartilhavam uma só. Veja Entrada humanizada.
• 0.41.0 no build licenciado a partir do r32: a persona chega ao navegador pelo ambiente dele, e não pela linha de comando, então uma ferramenta que lia o seed na lista de processos deixa de encontrá-lo (persona_env=False mantém o jeito antigo). Os contextos que uma inicialização local cria deixam de emular um esquema de cores claro, então uma persona escura reporta escuro em todo lugar (passe color_scheme para fixar um). Uma inicialização headless no Linux com uma persona recebe uma tela do tamanho que a persona declara. Veja Opções de inicialização.
• 0.41.0, .NET no Linux: as inicializações agora usam as fontes que vêm com o navegador, como o Python e o Node sempre fizeram, em vez das fontes do host. Uma persona Windows ali passa a medir de outro jeito, agora como nos outros dois SDKs. Veja suas próprias fontes no Linux.
• 0.41.0, uma persona Linux num computador Windows: o SDK avisa uma vez por processo. O Windows roda a GPU pelo Direct3D, que impõe um teto aos limites do WebGL e do WebGPU, e uma persona pode baixar um limite, mas nunca elevá-lo acima do limite do driver; por isso, uma persona Linux ali reporta limites que nenhuma máquina Linux tem. Declare Windows no Windows, ou rode personas Linux no Linux ou no Docker. quiet ou CLEARCOTE_NO_WARN silenciam o aviso.
• Imagem Docker sdk-0.41.0: o Chrome pode rodar com o sandbox, se você iniciar o contêiner com o perfil seccomp da imagem; sem ele, o contêiner roda como antes. As fontes de escrita já vêm embutidas. Veja Deploy.
• 0.40.0: no macOS, o launch() roda a imagem Docker do Clearcote (exige o Docker Desktop; docker=False desliga isso). Veja macOS.

Depois de atualizar, verifique de novo

Um build novo pode alterar algum sinal. Rode de novo os seus testes de fingerprint (por exemplo, CreepJS) e, se você usa um perfil importado, confirme que ele ainda carrega de forma coerente — veja Verificação. O build aberto atual é o v0.1.0-pre.23 (Chromium 150.0.7871.114); o build licenciado atual é o 154.0.8037.57-r36. O roadmap mostra o que vem por aí.