Installation

Installieren Sie das SDK und lassen Sie es einen verifizierten Browser holen — oder laden Sie einen Build selbst herunter und verifizieren Sie ihn.

Clearcote befindet sich in aktiver Entwicklung. Builds gibt es für Windows x64 und Linux x64 — das SDK lädt automatisch den passenden für Ihr Betriebssystem. Einen nativen macOS-Build gibt es nicht: Unter macOS startet launch() für Sie das Clearcote-Docker-Image (SDK 0.40.0+, siehe macOS). Auf einem minimalen Linux-Host installieren Sie die Laufzeitbibliotheken des Browsers (libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libpango-1.0-0 …) — clearcote info zeigt an, welche fehlen. Wenn Sie das Binary selbst als root starten (in Containern üblich), übergeben Sie --no-sandbox; das SDK und clearcote serve erledigen das für Sie.

SDK installieren (empfohlen)

npm i clearcote                # Node 20+
pip install clearcote          # Python 3.8+
dotnet add package Clearcote   # .NET 8

Der erste Aufruf von launch() lädt den Browser für Ihr Betriebssystem herunter, prüft seine SHA-256-Prüfsumme und legt ihn im Cache ab. playwright install müssen Sie nicht ausführen — jedes SDK bringt seinen eigenen Playwright-Treiber mit und holt sich seinen Browser selbst. Welchen Build Sie bekommen, hängt davon ab, ob ein Lizenzschlüssel gesetzt ist:

Lizenzschlüssel setzen

Das SDK sucht den Schlüssel in dieser Reihenfolge: zuerst die Launch-Option licenseKey / license_key / LicenseKey, dann die Umgebungsvariable CLEARCOTE_LICENSE_KEY, dann ~/.clearcote/license.key — die Datei, die clearcote login schreibt. Jedes SDK, auch das für .NET, liest diese Datei. Einen kostenlosen Schlüssel erhalten Sie unter Lizenzen in Ihrem Dashboard.

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

Von einem anderen Gerät aus anmelden

clearcote login --device (SDK 0.40.0+, Python und Node; npx clearcote login --device bei einer lokalen npm-Installation) speichert einen Schlüssel, ohne dass Sie einen kopieren müssen. Der Befehl gibt einen Link und einen kurzen Code aus. Öffnen Sie den Link in einem Browser auf einem beliebigen Gerät, auf dem Sie sich bei clearcotelabs.com anmelden können, prüfen Sie, ob die Seite denselben Code zeigt wie Ihr Terminal, setzen Sie das Häkchen, mit dem Sie bestätigen, dass das Terminal Ihnen gehört, und geben Sie die Anmeldung frei. Die Seite meldet, dass das Gerät angemeldet ist, und das Terminal gibt Signed in as mit der (teilweise verborgenen) Adresse Ihres Kontos aus, dazu den Speicherort des Schlüssels sowie Tarif und Ablaufdatum. Der Schlüssel selbst wird nie ausgegeben, weder auf der Seite noch im Terminal.

Ein Code gilt 10 Minuten; danach führen Sie den Befehl erneut aus und erhalten einen neuen. Strg+C während des Wartens speichert nichts, ein zweites Strg+C bricht sofort ab. Nutzen Sie --device auf einem Server, den Sie per SSH erreichen, in einem Container oder wenn ein Coding-Agent Clearcote für Sie einrichtet: Die Freigabe erfolgt in Ihrem eigenen Browser, und nichts Geheimes läuft über das Terminal, dessen Verlauf oder einen Chat. Haben Sie den Schlüssel auf Ihrem eigenen Rechner zur Hand, ist clearcote login genauso gut: Seit 0.40.0 liest der Befehl den Schlüssel ein, ohne ihn anzuzeigen.

Der Befehl clearcote

Die Python- und Node-Pakete installieren den Befehl clearcote (bei einer lokalen npm-Installation rufen Sie ihn als npx clearcote … auf). Das .NET-Paket bringt keinen mit.

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

Jeder Befehl versteht --help. Ab SDK 0.40.0 testet clearcote info den Build, den launch() starten würde, auch einen über CLEARCOTE_BROWSER_VERSION gewählten, und zeigt an, wann der Schlüssel abläuft, sofern er mit clearcote login --device gespeichert wurde (für einen eingefügten Schlüssel meldet kein Lizenzdienst das Ablaufdatum). Ab 0.41.0 meldet er unter Linux außerdem, welche Schriftsysteme die Schriften, die ein Launch sehen würde, darstellen können (siehe eigene Schriften unter Linux). Mit clearcote install --version 154 oder --channel preview wählen Sie einen bestimmten Build; siehe Build auswählen. Als Nächstes binden Sie ihn in Playwright oder Puppeteer ein.

macOS

Einen nativen macOS-Build gibt es nicht. Ab SDK 0.40.0 startet launch() unter macOS das Clearcote-Docker-Image (teamflatearth/clearcote:sdk-<SDK version>, ein linux/amd64-Image, das Docker Desktop auf Intel und Apple Silicon ausführt), verbindet sich damit und liefert denselben Playwright-Browser wie ein lokaler Start. Ihr Code ändert sich nicht, und close() stoppt und entfernt den Container. Das gilt für launch() in Python (sync und async), Node und .NET (LaunchAsync); die anderen Einstiegspunkte, etwa persistente Kontexte und serve(), brauchen weiterhin ein Clearcote-Binary. Auf einem Mac führen Sie diese daher direkt im Docker-Image aus.

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

• Docker Desktop muss installiert sein und laufen. Andernfalls löst launch() einen DockerUnavailableError (.NET: DockerUnavailableException) aus, der erklärt, was zu tun ist. Der erste Start lädt das Image und, mit Lizenzschlüssel, den neuesten Build einmalig in das Volume clearcote-cache; spätere Starts dauern nur Sekunden.
• Was in den Container gelangt: die Persona-Optionen, headless, proxy, args, version und der Lizenzschlüssel (der wie auf jedem anderen Rechner gefunden wird, auch der von clearcote login gespeicherte). Eine Option, die der Container nicht übernehmen kann, wird mit ihrem Namen abgelehnt. Schlüssel und Proxy erreichen den Container als Datei, die er einmal liest und dann löscht, sodass docker inspect sie nicht anzeigt; ein Start mit Schlüssel oder Proxy wird abgelehnt, wenn der Container nicht den lizenzierten Build bzw. den Proxy verwendet.
• Nichts läuft weiter. Endet Ihr Programm ohne close() oder wird es abgebrochen, stoppt sein Container von selbst etwa 30 Sekunden, nachdem keine Verbindung mehr zu ihm besteht, und der nächste Start entfernt Überreste, deren Programm nicht mehr läuft. Container, die zu anderen laufenden Programmen, anderen Benutzern oder anderen Rechnern gehören, werden nie angetastet. Seit SDK 0.41.0 kehrt close() erst zurück, wenn Docker den Container und sein Volume entfernt hat; docker ps -a listet ihn danach also nicht mehr auf.
• Chrome behält seine Sandbox (SDK 0.41.0+ mit einem Image ab sdk-0.41.0): Der Start übergibt das seccomp-Profil des Images, sodass Chrome im Container mit seiner Sandbox läuft (siehe Die Sandbox von Chrome). Dafür braucht es Docker auf einer x86_64-CPU; auf Apple Silicon läuft das Image emuliert, und die Sandbox bleibt dort vorerst aus.
• Der Container läuft unter Linux, daher ist seine Standard-Persona eine Linux-Persona. Lesen Sie Deployment, bevor Sie aus einem Container heraus eine andere Plattform vorgeben.

Ein Image wird einige Minuten nach dem zugehörigen SDK-Release veröffentlicht; direkt nach einem Upgrade gibt es das passende Tag daher eventuell noch nicht. Die Fehlermeldung weist darauf hin, und bis dahin kann CLEARCOTE_DOCKER_IMAGE auf ein früheres Tag zeigen.

Manuelle Installation (offener Build)

Lieber das nackte Binary? Auf GitHub Releases liegt der offene Build. Der lizenzierte Build wird dort nicht veröffentlicht: Er läuft über das SDK, clearcote serve oder das Docker-Image und startet nicht ohne das Run-Token, das das SDK bereitstellt.

1. Herunterladen

Laden Sie das neueste Release v0.1.0-pre.* herunter — derzeit v0.1.0-pre.23 (Chromium 150.0.7871.114). Jedes Release enthält:

• clearcote-<version>-windows-x64.zip — den Windows-Build (Chromium + Runtime + VC++-DLLs)
• clearcote-<version>-linux-x64.tar.xz — den Linux-Build
• .sha256-Dateien und SHA256SUMS.txt — die Prüfsummen
• .asc-Dateien + clearcote-signing-key.asc — abgetrennte GPG-Signaturen und den öffentlichen Schlüssel

2. Verifizieren (empfohlen)

Der offene Build ist so angelegt, dass Sie uns nicht vertrauen müssen. Prüfen Sie vor dem Entpacken, ob der Download exakt dem entspricht, was gebaut und signiert wurde — siehe Verifizierung.

3. Entpacken

Das Windows-Archiv ist in sich vollständig: Die Laufzeit-DLLs von VC++ 2015–2022 liegen bei, es läuft also auf einem frisch installierten Windows 10/11. Das Linux-Archiv braucht die oben genannten Laufzeitbibliotheken.

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

Starten Sie den Browser mit einem Seed auf einer Fingerprint-Testseite:

C:\clearcote\chrome.exe --fingerprint=seed-123 --fingerprint-platform=windows https://abrahamjuliot.github.io/creepjs/

Gleicher --fingerprint-Seed ⇒ bei jedem Start dieselbe Identität; neuer Seed ⇒ eine neue. Sollen statt der aus dem Seed abgeleiteten Werte die erfassten Werte eines echten Rechners gemeldet werden, importieren Sie ein erfasstes Profil — siehe Fingerprint-Flags. Binden Sie den Browser anschließend in Playwright oder Puppeteer ein.

In Docker ausführen

Das offizielle Image betreibt Clearcote als CDP-Endpunkt: Image ziehen und einen beliebigen Playwright-, Puppeteer- oder browser-use-Client per Chrome DevTools Protocol darauf richten, ohne Codeänderung.

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

Die Persona konfigurieren Sie über Umgebungsvariablen — CC_PLATFORM (windows/linux/macos/android), CC_FINGERPRINT (Seed), CC_BRAND (Edge…), CC_ACCEPT_LANGUAGE, CC_TIMEZONE, CC_TLS_PROFILE. Ohne CC_FINGERPRINT bekommt jeder Container einen eigenen zufälligen Seed, der Neustarts überdauert; setzen Sie die Variable, um eine Identität gezielt zu wählen oder wiederzuverwenden. Das Image enthält den offenen Build; mit -e CLEARCOTE_LICENSE_KEY=cc_lic_… -v clearcote-cache:/opt/xdg-cache läuft der neueste lizenzierte Build, der einmalig in das Volume heruntergeladen wird. Der Browser läuft im Headed-Modus auf einem virtuellen Display (CC_HEADLESS=1 für reinen Headless-Betrieb), und das Image ist linux/amd64. Das Dockerfile ist nachprüfbar — bauen Sie es selbst neu. Wer den CDP-Endpunkt erreicht, hat volle Kontrolle über den Browser; geben Sie ihn daher nur in vertrauenswürdigen Netzen frei (-p 127.0.0.1:9222:9222 hält ihn lokal auf dem Host). Mehr dazu unter Deployment.

Voraussetzungen

• Windows 10 / 11 x64 oder Linux x64 (glibc) mit den oben genannten Laufzeitbibliotheken.
• macOS (Intel oder Apple Silicon): ein laufendes Docker Desktop für launch() (SDK 0.40.0+).
• Unter Windows ist kein separates VC++ Redistributable nötig — es liegt dem Archiv bei.
• SDK: Node 20+, Python 3.8+ oder .NET 8. Jedes bringt seinen eigenen Playwright-Treiber mit (playwright-core, playwright, Microsoft.Playwright).
• Wenn Sie das Binary des offenen Builds direkt verwenden: Ihre vorhandene Playwright- oder Puppeteer-Installation (Clearcote ersetzt den Browser, nicht den Treiber).