インストール

SDK をインストールして検証済みのブラウザを取得させるか、ビルドを自分でダウンロードして検証します。

Clearcote は現在も活発に開発中です。ビルドは Windows x64 版と Linux x64 版を提供しており、SDK は OS に合ったほうをダウンロードします。macOS 向けのネイティブビルドはありません。macOS では、launch() が Clearcote の Docker イメージを自動で実行します（SDK 0.40.0+。macOS を参照）。最小構成の Linux ホストでは、ブラウザのランタイムライブラリ（libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libpango-1.0-0 …）をインストールしてください。不足しているものは clearcote info で一覧表示できます。自分でバイナリを root として起動する場合（コンテナではよくあるケース）は --no-sandbox を渡してください。SDK と clearcote serve はこれを自動で処理します。

SDK をインストールする（推奨）

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

最初の launch() で OS に合ったブラウザがダウンロードされ、SHA-256 を確認したうえでキャッシュされます。playwright install を実行する必要はありません。各 SDK は自前の Playwright ドライバーを同梱し、ブラウザも自分で取得します。どのビルドが使われるかは、ライセンスキーを設定しているかどうかで決まります。

ライセンスキーを設定する

SDK は次の順にキーを探します。まず起動オプションの licenseKey / license_key / LicenseKey、次に環境変数 CLEARCOTE_LICENSE_KEY、その次に clearcote login が書き込むファイル ~/.clearcote/license.key です。このファイルは .NET を含むすべての SDK が読み込みます。無料のキーは、ダッシュボードの「Licenses」から取得できます。

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

別のデバイスからサインインする

clearcote login --device（SDK 0.40.0+、Python と Node。npm でローカルにインストールした場合は npx clearcote login --device）を使うと、キーを自分でコピーしなくても保存できます。コマンドはリンクと短いコードを表示します。clearcotelabs.com にサインインできる任意のデバイスのブラウザでそのリンクを開き、ページに表示されたコードがターミナルのものと同じであることを確かめ、そのターミナルが自分のものであることを確認するチェックボックスをオンにして、承認します。ページにはデバイスがサインインしたことが表示され、ターミナルには Signed in as に続いてアカウントのメールアドレス（一部を伏せた形）、キーの保存先、プランと有効期限が表示されます。キーそのものは、ページにもターミナルにも表示されません。

コードの有効期間は 10 分です。期限が切れたら、コマンドをもう一度実行して新しいコードを取得してください。待機中に Ctrl-C を押すと何も保存されず、もう一度 Ctrl-C を押すとすぐに終了します。--device は、SSH で接続するサーバー上やコンテナ内で使うとき、またはコーディングエージェントに Clearcote をセットアップさせるときに使ってください。承認は自分のブラウザで行われ、秘密情報がターミナルやその履歴、チャットを通ることはありません。自分のマシンでキーが手元にあるなら、clearcote login でも十分です。0.40.0 以降は、キーを画面に表示せずに読み取ります。

clearcote コマンド

Python と Node のパッケージは clearcote コマンドをインストールします（npm でローカルにインストールした場合は npx clearcote … として実行します）。.NET のパッケージには含まれていません。

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

どのコマンドも --help を受け付けます。SDK 0.40.0 以降、clearcote info は launch() が実行するビルド（CLEARCOTE_BROWSER_VERSION で指定したビルドを含む）をテストし、キーを clearcote login --device で保存した場合はその有効期限も表示します（貼り付けたキーの有効期限は、どのライセンスサービスからも通知されません）。0.41.0 以降は Linux で、起動時にブラウザから見えるフォントがどの文字体系を描画できるかも報告します（Linux で独自のフォントを使うを参照）。clearcote install --version 154 や --channel preview で特定のビルドを選べます。詳しくはビルドの選び方を参照してください。次は Playwright または Puppeteer に組み込みます。

macOS

macOS 向けのネイティブビルドはありません。SDK 0.40.0 以降、macOS で launch() を呼ぶと Clearcote の Docker イメージ（teamflatearth/clearcote:sdk-<SDK version>。Docker Desktop が Intel と Apple シリコンのどちらでも実行できる linux/amd64 イメージです）が起動し、SDK はそこに接続して、ローカルで起動したときと同じ Playwright ブラウザを返します。コードを変える必要はなく、close() でコンテナが停止・削除されます。対象は Python（同期・非同期）、Node、.NET（LaunchAsync）の launch() です。永続コンテキストや serve() などのほかのエントリーポイントには引き続き Clearcote のバイナリが必要なため、Mac ではそれらを Docker イメージの中で直接実行してください。

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 がインストールされ、起動している必要があります。そうでない場合、launch() は対処方法を示す DockerUnavailableError（.NET では DockerUnavailableException）を送出します。初回の起動ではイメージをダウンロードし、ライセンスキーがあれば最新ビルドも clearcote-cache ボリュームに一度だけダウンロードします。次回以降の起動は数秒で始まります。
• コンテナに渡されるもの：ペルソナのオプション、headless、proxy、args、version、ライセンスキー（ほかのマシンと同じ方法で探され、clearcote login で保存したキーも含みます）。コンテナが受け付けられないオプションは、名前を示して拒否されます。キーとプロキシは、コンテナが一度だけ読み込んで削除するファイルとして渡されるため、docker inspect には表示されません。また、キーやプロキシを指定した起動は、コンテナがライセンスビルドを実行していない場合やそのプロキシを使っていない場合には拒否されます。
• 何も動いたまま残りません。プログラムが close() を呼ばずに終了したり強制終了されたりしても、そのコンテナは接続がなくなってから約 30 秒後に自動で停止します。また、次回の起動時に、元のプログラムがもう存在しない残りのコンテナが削除されます。実行中のほかのプログラム、ほかのユーザー、ほかのマシンに属するコンテナには一切手を触れません。SDK 0.41.0 以降、close() は Docker がコンテナとそのボリュームを削除し終えてから戻るため、その後 docker ps -a に表示されることはありません。
• Chrome はサンドボックスを維持します（SDK 0.41.0+ と sdk-0.41.0 以降のイメージ）。起動時にイメージの seccomp プロファイルを渡すため、Chrome はコンテナ内でサンドボックスありで動作します（Chrome のサンドボックスを参照）。これには x86_64 CPU 上の Docker が必要です。Apple シリコンではイメージがエミュレーションで動作するため、現時点ではサンドボックスはオフのままです。
• コンテナでは Linux が動作します。そのため、デフォルトのペルソナは Linux のものです。コンテナから別のプラットフォームを名乗る前に、デプロイを読んでください。

イメージは SDK のリリースから数分後に公開されるため、アップグレードの直後には対応するタグがまだ存在しないことがあります。その場合はエラーでそのことが示されます。それまでの間は、CLEARCOTE_DOCKER_IMAGE で以前のタグを指定できます。

手動インストール（オープンビルド）

バイナリを直接使いたい場合は、GitHub Releases にオープンビルドがあります。ライセンスビルドはそこでは公開していません。ライセンスビルドは SDK、clearcote serve、Docker イメージのいずれかを通じて動作し、SDK が用意する実行トークンがなければ起動しません。

1. ダウンロード

最新の v0.1.0-pre.* リリースをダウンロードしてください。現在の最新は v0.1.0-pre.23（Chromium 150.0.7871.114）です。各リリースには次のファイルが含まれます。

• clearcote-<version>-windows-x64.zip — Windows 版ビルド（Chromium + ランタイム + VC++ DLL）
• clearcote-<version>-linux-x64.tar.xz — Linux 版ビルド
• .sha256 ファイルと SHA256SUMS.txt — チェックサム
• .asc ファイル + clearcote-signing-key.asc — GPG の分離署名と公開鍵

2. 検証する（推奨）

オープンビルドは、私たちを信頼しなくても済むように作られています。展開する前に、ダウンロードしたものがビルド・署名されたものと完全に一致することを確認してください。手順は検証のページにあります。

3. 展開する

Windows 版のアーカイブはそれだけで完結しています。VC++ 2015–2022 のランタイム DLL を同梱しているため、クリーンな Windows 10/11 マシンでそのまま動作します。Linux 版のアーカイブには、上に挙げたランタイムライブラリが必要です。

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. スモークテスト

シードを指定して起動し、フィンガープリントテストのページを開きます。

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

--fingerprint のシードが同じなら、起動するたびに同じアイデンティティになります。新しいシードなら新しいアイデンティティです。シードから導出した値ではなく実機から取得した値を返したい場合は、取得済みのプロファイルをインポートします（フィンガープリントフラグを参照）。そのあと Playwright または Puppeteer に組み込みます。

Docker で実行する

公式イメージは Clearcote を CDP エンドポイントとして実行します。イメージを pull し、Playwright、Puppeteer、browser-use などのクライアントを Chrome DevTools Protocol 経由でそこへ向けるだけで、コードの変更は要りません。

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

ペルソナは環境変数で設定します。CC_PLATFORM（windows/linux/macos/android）、CC_FINGERPRINT（シード）、CC_BRAND（Edge など）、CC_ACCEPT_LANGUAGE、CC_TIMEZONE、CC_TLS_PROFILE です。CC_FINGERPRINT を設定しないと、コンテナごとにランダムなシードが割り当てられ、再起動後も維持されます。アイデンティティを選んだり再利用したりするには、この変数を設定します。イメージに入っているのはオープンビルドです。最新のライセンスビルドを使うには -e CLEARCOTE_LICENSE_KEY=cc_lic_… -v clearcote-cache:/opt/xdg-cache を追加します。ビルドはボリュームに一度だけダウンロードされます。ブラウザは仮想ディスプレイ上で headed モードで動作し（純粋なヘッドレスにするには CC_HEADLESS=1）、イメージは linux/amd64 です。Dockerfile は監査可能なので、自分で再ビルドしてみてください。CDP エンドポイントはブラウザを完全に制御できるため、信頼できるネットワークにだけ公開してください（-p 127.0.0.1:9222:9222 ならホスト内に限定されます）。詳しくはデプロイを参照してください。

動作要件

• Windows 10 / 11 x64、または上記のランタイムライブラリを入れた Linux x64（glibc）。
• macOS（Intel または Apple シリコン）：launch() には Docker Desktop が起動している必要があります（SDK 0.40.0+）。
• Windows では VC++ 再頒布可能パッケージを別途入れる必要はありません。アーカイブに同梱されています。
• SDK：Node 20+、Python 3.8+、または .NET 8。それぞれ専用の Playwright ドライバー（playwright-core、playwright、Microsoft.Playwright）を取り込みます。
• オープンビルドのバイナリを直接使う場合：既存の Playwright または Puppeteer のインストール（Clearcote が置き換えるのはブラウザで、ドライバーではありません）。