Migrer depuis Fortress (versions BSD)

Si vous utilisez l’une des versions de Fortress sous licence BSD (v149, v150 ou v151) comme endpoint CDP, vous pouvez migrer cette configuration vers Clearcote en changeant la façon dont le navigateur démarre. Le code qui se connecte à l’endpoint reste le même.

Fortress est passé à sa propre licence source-available avec la v3 (Chromium 153), le 30 septembre 2026, et ses versions antérieures conservent leur licence BSD-3. Ce guide s’adresse aux équipes qui utilisent l’une de ces versions BSD et préfèrent passer à Clearcote plutôt qu’à la v3. Pour comparer licences, prix et plateformes, voir Clearcote vs Fortress.

Ce qui change

Tout ce qui suit l’appel de connexion, votre code Playwright, Puppeteer, browser-use, Crawl4AI ou Stagehand, reste tel quel. Un point à vérifier d’abord : le tag d’image tilion/fortress:latest pointe vers la v3 depuis le 30 septembre 2026, donc une configuration qui récupère :latest n’est plus sur une version BSD. Épinglez :149, :150 ou :151 jusqu’à ce que vous ayez fait la bascule.

Python et Node : serve()

serve() démarre Clearcote avec les réglages de lancement du SDK (persona, proxy, valeurs par défaut) et un endpoint CDP sur l’interface loopback, puis renvoie un handle contenant l’URL de l’endpoint. Passez port=9222 si d’autres parties du code attendent l’ancienne adresse ; sinon, serve() choisit un port libre.

# 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

close() arrête le navigateur, attend qu’il se termine et supprime le profil temporaire créé par serve() ; en Python, le bloc with l’appelle pour vous. Pour browser-use, Crawl4AI ou Stagehand, donnez srv.cdp_url à leur paramètre CDP (Node : srv.cdpUrl). Le SDK .NET propose le même appel sous le nom ServeAsync. Plus de détails dans Puppeteer et autres clients CDP.

Docker

Changez d’image et gardez le port. Le client se connecte à la même adresse qu’avant.

# 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

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 garde l’endpoint sur cette machine : un port CDP donne le contrôle total du navigateur, ne le publiez donc que sur des réseaux de confiance. Définissez CC_FINGERPRINT pour choisir ou réutiliser une identité : sans cette variable, les images à partir de sdk-0.39.0 donnent à chaque conteneur un seed aléatoire, et les plus anciennes donnent le même à tous. L’image se configure entièrement par variables d’environnement (plateforme, langue, fuseau horaire, proxy), listées dans Déploiement.

Depuis le shell : clearcote serve

Si vous lanciez vous-même le binaire ou le launcher tilion et que vos clients pointaient vers le port 9222, clearcote serve (fourni avec les packages Python et Node) prend le relais en tant que serveur permanent. Une connexion sans paramètres obtient un navigateur par défaut partagé, donc les clients existants fonctionnent sans changement ; une connexion peut aussi demander sa propre identité dans l’URL.

# 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

Ce qui fonctionne différemment

• L’identité vient d’une seed. Dans les versions BSD, le launcher de Fortress applique par défaut un seul persona Windows cohérent, que vous modifiez surface par surface avec les switches --uxr-* (--uxr-timezone, --uxr-languages, --uxr-screen-width, --uxr-canvas-seed, etc.) ou TILION_TZ / TILION_LANG. Clearcote dérive tout le persona, y compris le bruit canvas et WebGL par site, d’une seule seed fingerprint, si bien que la même seed donne toujours la même identité et qu’une nouvelle seed en donne une sans rapport. Donnez à chaque compte sa propre seed plutôt que de reporter une à une les valeurs --uxr-* ; définissez la plateforme avec platform, le fuseau horaire et les langues avec timezone et accept_language (Node : acceptLanguage), ou laissez geoip les faire correspondre au proxy. Voir Réglages recommandés.
• Ouvrez les pages dans le profil servi. Utilisez browser.contexts[0] comme dans les exemples. Avec Puppeteer, connectez-vous avec defaultViewport: null pour que la fenêtre garde la taille que le persona lui a donnée.
• Confiez le proxy à Clearcote, pas au client. Passez proxy à serve(), ou --proxy à clearcote serve, et activez geoip pour que le fuseau horaire, les langues et l’adresse WebRTC correspondent à l’IP de sortie. Un proxy avec nom d’utilisateur et mot de passe nécessite le dernier build ; sur le build ouvert, utilisez un proxy qui autorise par IP. Voir Proxys et geoip.
• Les switches et variables d’environnement propres à Fortress n’ont aucun effet ici. Les options de Clearcote sont décrites dans Options de lancement et Flags d’empreinte.
• Les entrées humanisées sont une option de launch(). Elles s’exécutent côté Playwright et ne s’appliquent donc pas à un client connecté via CDP.
• Mêmes plateformes que les versions BSD : Windows x64 et Linux x64, et l’image Docker est en x64.

Quel build de Clearcote vous obtenez

Sans clé de licence, le SDK et l’image exécutent le build ouvert : BSD-3, chaque patch public et reproductible, sur Chromium 150, sans compte. Avec une clé, ils exécutent le dernier build (Chromium 154), qui ajoute des patchs privés : gratuit avec GitHub pour un navigateur à la fois, et Pro pour davantage. Enregistrez la clé avec clearcote login ou définissez CLEARCOTE_LICENSE_KEY ; voir Installation.

Vérifier la bascule

Une fois l’endpoint lancé, demandez-lui ce qu’il est :

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

clearcote info affiche le tag de build qu’il résout et Launch test ok avec la version exacte du navigateur. La procédure d’installation indique quelle version chaque build doit annoncer, et que faire quand une vérification échoue.