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. Auf einem Mac mit Apple Silicon läuft der Browser nativ (der lizenzierte Build als Preview, ohne Lizenzschlüssel der offene 150-Build); auf einem Intel-Mac startet launch() für Sie das Clearcote-Docker-Image (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                 # 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

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.

Ab 0.56.0 beginnt clearcote info mit dem Rechner selbst (Prozessor, Arbeitsspeicher, Betriebssystem, virtuelle Maschine oder Container und ob es eine Grafikkarte gibt, mit der der Browser zeichnen kann). clearcote bench startet --concurrency Browser (Standard 3), lädt --url für --duration Sekunden (Standard 30), über --proxy, falls angegeben, und meldet, was jeder Browser auf diesem Rechner an CPU-Threads und RAM kostet, die Ladezeiten, Fehler, wie viele Browser der Rechner ungefähr gleichzeitig schafft und was Sie ändern sollten. Ist zu wenig Arbeitsspeicher frei, startet er weniger Browser (--force startet alle), und jeder Browser belegt während des Laufs einen Lizenzplatz. Fügen Sie die Ausgabe in eine Support-Anfrage ein. In .NET liefern ClearcoteBench.RunAsync und ClearcoteHost.Info denselben Bericht im Code.

Ab 0.61.0 startet clearcote connect den Clearcote Helper in diesem Terminal, damit die Web-Version des Profile Manager unter app.clearcotelabs.com Ihre Profile auf diesem Computer starten kann. Wählen Sie in ihrem Fenster „Connect“ I use the Clearcote SDK und führen Sie den angezeigten Befehl mit seinem Einmalcode aus (npx clearcote connect 4F7-K2Q): Dieser Tab verbindet sich von selbst, ohne Bestätigungsseite. Beim ersten Start lädt das SDK die Helper-Version herunter, die es festlegt, und prüft ihre SHA-256. Lassen Sie das Terminal offen; Strg+C beendet den Helper und seine Browser.

macOS

Auf einem Mac mit Apple Silicon (M1 oder neuer, macOS 13 oder neuer) und mit Lizenzschlüssel lädt das SDK (0.51.1+) den lizenzierten macOS-Build herunter und startet ihn nativ, wie unter Windows und Linux. Er ist eine Preview und kann hinter Windows und Linux zurückliegen: Derzeit ist es 155.0.8059.39-r49, während dort 156.0.8078.47-r57 läuft. Ohne Lizenzschlüssel lädt das SDK (0.68.4+) den offenen 150-Build für Apple Silicon herunter (v0.1.0-pre.24, eine Chromium-Version hinter den offenen Builds für Windows und Linux) und startet ihn ebenfalls nativ.

Auf einem Intel-Mac (und mit SDK 0.40.0 bis 0.68.3 auf jedem Mac ohne Lizenzschlüssel) startet launch() 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.25 (Chromium 151.0.7922.108). 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-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

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.

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

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.

Download-Limits

Downloads des lizenzierten Builds sind pro Lizenz begrenzt, damit ein Setup, das bei jedem Start das ganze Archiv lädt, nicht ausufern kann. Ein Start, der den Build im Cache findet, lädt nichts herunter und zählt nie — nur echte Downloads zählen.

Über einem Limit erhält das SDK HTTP 429 mit einem JSON-Body — code ist DOWNLOAD_RATE_LIMITED (Kontingent pro Build) oder DOWNLOAD_LIMIT_EXCEEDED (kostenloser Plan) — und einem Retry-After-Header: die Sekunden, bis das Limit zurückgesetzt wird. Starts, deren Build schon im Cache liegt, funktionieren weiter. Ab SDK 0.62.0 startet ein Start, der einen neuen Build nicht herunterladen kann, statt mit einem Fehler den neuesten Build derselben Chromium-Version aus seinem Cache und wartet Retry-After ab, bevor er diesen Download erneut versucht. Ein Start, der auf eine exakte Revision (r50) festgelegt ist, bekommt weiterhin genau diesen Build oder einen Fehler.

Diese Limits erreichen Sie, wenn viele frische Maschinen oder Container gleichzeitig starten, jeder mit leerem Cache. Laden Sie jeden Build einmal pro Maschine statt einmal pro Start — so starten sie auch schneller, ohne einen Download von etwa 460 MB:

• Halten Sie den Cache auf einem Volume. Richten Sie CLEARCOTE_CACHE auf ein Verzeichnis, das Neustarts übersteht. Starts, die es teilen, warten auf den ersten Download und nutzen ihn.
• Backen Sie den Browser in Ihr Image. Führen Sie clearcote install beim Build aus, damit jeder Container mit dem Build startet. Bauen Sie das Image beim Upgrade neu.

# 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

Persona-Limits

Jeder Start holt seine Persona (den Fingerprint, den Seed und Optionen beschreiben) vom Persona-Dienst. Jede Lizenz kann pro Tag eine feste Anzahl verschiedener Personas abrufen. Eine Persona, die Sie heute schon genutzt haben, erneut abzurufen, kostet nichts; ein fester Satz von Profilen kann also beliebig oft neu starten.

Eine Persona ist ein Seed mit einem Satz von Fingerprint-Optionen (Marke, Plattform usw.); derselbe Seed als Chrome und als Edge zählt also doppelt. Der Zähler wird um 00:00 UTC zurückgesetzt. Über dem Limit schlägt der Start mit HTTP 429 vom Persona-Dienst fehl (daily persona quota reached), bis zum Zurücksetzen.

Das passiert, wenn jeder Start einen brandneuen zufälligen Seed verwendet. Nutzen Sie stattdessen einen festen Pool von Seeds, etwa eine Liste von einigen hundert Namen, die Sie reihum verwenden: Jeder behält bei jedem Start denselben Fingerprint, und ein erneuter Start zählt nie noch einmal.

Voraussetzungen

• Windows 10 / 11 x64 oder Linux x64 (glibc) mit den oben genannten Laufzeitbibliotheken.
• macOS: auf Apple Silicon (macOS 13+) nichts weiter (SDK 0.51.1+ mit Lizenzschlüssel, 0.68.4+ ohne). Auf einem Intel-Mac 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).