Pular para o conteúdo

Migrando do Fortress (versões BSD)

Se você usa uma das versões do Fortress sob licença BSD (v149, v150 ou v151) como endpoint CDP, pode migrar a configuração para o Clearcote mudando a forma como o navegador é iniciado. O código que se conecta ao endpoint continua igual.

Em 30 de setembro de 2026, com a v3 (Chromium 153), o Fortress passou a usar uma licença própria de código-fonte disponível (source-available), e as versões anteriores mantêm a licença BSD-3. Este guia é para equipes em uma dessas versões BSD que preferem migrar para o Clearcote em vez de ir para a v3. Para ver licenças, preços e plataformas lado a lado, confira Clearcote vs Fortress.

O que muda

Você inicia o Fortress comInicie o Clearcote com
Python: Fortress() de tilion-fortress, depois f.cdp_urlserve() de clearcote, depois srv.cdp_url
Node: Fortress.launch(), depois f.cdpUrlawait serve() de clearcote, depois srv.cdpUrl
Docker: tilion/fortress:149, :150 ou :151 na porta 9222teamflatearth/clearcote na porta 9222
O launcher tilion ou o binário com --remote-debugging-port=9222clearcote serve --port 9222

Tudo o que vem depois da chamada de conexão, ou seja, seu código de Playwright, Puppeteer, browser-use, Crawl4AI ou Stagehand, continua como está. Uma coisa para verificar antes: a tag de imagem tilion/fortress:latest aponta para a v3 desde 30 de setembro de 2026, então uma configuração que baixa :latest já não está em uma versão BSD. Fixe :149, :150 ou :151 até concluir a troca.

Python e Node: serve()

O serve() inicia o Clearcote com as configurações de inicialização do SDK (persona, proxy, padrões) e um endpoint CDP em loopback, e retorna um handle com a URL do endpoint. Passe port=9222 se outro código espera o endereço antigo; sem isso, o serve() escolhe uma porta livre.

# pip install -U clearcote
from clearcote import serve
from playwright.sync_api import sync_playwright

with serve(fingerprint="acct-1", port=9222) as srv:        # was: with Fortress() as f:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(srv.cdp_url)  # was: f.cdp_url
        page = browser.contexts[0].new_page()               # the served profile
        page.goto("https://example.com")
        print(page.title())
        browser.close()                                     # disconnect before the with blocks end

O close() encerra o navegador, espera até que ele termine e remove o perfil temporário que o serve() criou; em Python, o bloco with faz essa chamada por você. No browser-use, no Crawl4AI ou no Stagehand, passe srv.cdp_url (Node: srv.cdpUrl) na configuração de CDP de cada um. O SDK .NET tem a mesma chamada como ServeAsync. Mais em Puppeteer e outros clientes CDP.

Docker

Troque a imagem e mantenha a porta. O cliente se conecta ao mesmo endereço de antes.

bash
# was: docker run --rm -p 9222:9222 tilion/fortress:151
docker run -d --rm -p 127.0.0.1:9222:9222 -e CC_FINGERPRINT=acct-1 teamflatearth/clearcote

# the latest build: pass your key from the environment and keep the download in a volume
docker run -d --rm -p 127.0.0.1:9222:9222 -e CC_FINGERPRINT=acct-1 \
  -e CLEARCOTE_LICENSE_KEY -v clearcote-cache:/opt/xdg-cache teamflatearth/clearcote
python
browser = p.chromium.connect_over_cdp("http://localhost:9222")   # unchanged
page = browser.contexts[0].new_page()                            # the container's own profile

-p 127.0.0.1:9222:9222 mantém o endpoint nesta máquina: uma porta CDP dá controle total do navegador, então publique-a só em redes em que você confia. Defina CC_FINGERPRINT para escolher ou reutilizar uma identidade: sem ela, as imagens a partir de sdk-0.39.0 dão a cada contêiner uma seed aleatória própria, e as mais antigas dão a mesma a todos. A imagem é configurada inteiramente por variáveis de ambiente (plataforma, idioma, fuso horário, proxy), listadas em Deploy.

Pelo shell: clearcote serve

Se você mesmo iniciava o binário ou o launcher tilion e apontava os clientes para a porta 9222, o clearcote serve (nos pacotes Python e Node) é o substituto que fica em execução. Uma conexão sem parâmetros recebe um navegador padrão compartilhado, então os clientes existentes funcionam sem mudanças; uma conexão também pode pedir a própria identidade na URL.

bash
# was: tilion --headless=new --remote-debugging-port=9222 --user-data-dir=/tmp/p
clearcote serve --port 9222

#   connect_over_cdp("http://127.0.0.1:9222")                     # the shared default browser
#   connect_over_cdp("http://127.0.0.1:9222?fingerprint=acct-1")  # a browser of its own for acct-1

O que funciona de outro jeito

  • A identidade vem de uma seed. Nas versões BSD, o launcher do Fortress aplica uma única persona padrão de Windows, coerente, e você a altera superfície por superfície com os switches --uxr-* (--uxr-timezone, --uxr-languages, --uxr-screen-width, --uxr-canvas-seed e assim por diante) ou com TILION_TZ / TILION_LANG. O Clearcote deriva a persona inteira, incluindo o ruído de canvas e WebGL por site, de uma única seed fingerprint, então a mesma seed gera sempre a mesma identidade e uma seed nova gera uma identidade sem relação com a anterior. Dê a cada conta uma seed própria em vez de transpor os valores de --uxr-* um por um; defina a plataforma com platform, e o fuso horário e os idiomas com timezone e accept_language (Node: acceptLanguage), ou deixe o geoip ajustá-los ao proxy. Veja Configurações recomendadas.
  • Abra as páginas no perfil servido. Use browser.contexts[0] como nos exemplos. Com o Puppeteer, conecte com defaultViewport: null para que a janela mantenha o tamanho que a persona definiu.
  • Entregue o proxy ao Clearcote, não ao cliente. Passe proxy para o serve(), ou --proxy para o clearcote serve, e ative o geoip para que o fuso horário, os idiomas e o endereço WebRTC correspondam à saída. Um proxy com usuário e senha precisa do build mais recente; no build aberto, use um que autorize por IP. Veja Proxies e geoip.
  • Os switches e as variáveis de ambiente próprios do Fortress não têm efeito aqui. As opções do Clearcote estão em Opções de inicialização e Flags de fingerprint.
  • A entrada humanizada é uma opção do launch(). Ela roda do lado do Playwright, então não se aplica a um cliente conectado via CDP.
  • As mesmas plataformas das versões BSD: Windows x64 e Linux x64, e a imagem Docker é x64.

Qual build do Clearcote você recebe

Sem chave de licença, o SDK e a imagem rodam o build aberto: BSD-3, com todos os patches públicos e reproduzíveis, no Chromium 150, sem precisar de conta. Com uma chave, eles rodam o build mais recente (Chromium 154), que adiciona patches privados: grátis com GitHub para um navegador por vez e o Pro para mais. Salve a chave com clearcote login ou defina CLEARCOTE_LICENSE_KEY; veja Instalação.

Confira a troca

Com o endpoint em execução, pergunte o que ele é:

bash
curl -s http://127.0.0.1:9222/json/version   # the browser behind the endpoint
clearcote info                                # SDK, licence, cached build and a launch test

O clearcote info mostra a tag de build que ele resolve e Launch test ok com a versão exata do navegador. O runbook de instalação lista qual versão cada build deve informar e o que fazer quando uma verificação falha.