Clearcote を最新の状態に保つ

ライセンスキーがない場合、SDK の各バージョンは SHA-256 で検証済みのオープンビルド 1 つに固定されており、更新は通常のパッケージのバージョンアップで済みます。キーがある場合は、SDK が起動のたびに現行のライセンスビルドを取得するので、バージョンアップは不要です。

利用できるビルド

現在提供中または開発中の Chromium メジャーバージョンと、各ティアで利用できるようになる時期：

SDK を使う場合（推奨）

ほかの依存関係と同じようにパッケージを更新します：

npm i clearcote@latest          # Node
pip install -U clearcote        # Python
dotnet add package Clearcote    # .NET (adds or updates to the newest version)

次に launch() を呼んだとき、SDK は必要なビルドがキャッシュにないことを検知してダウンロードし（オープンビルドは GitHub Releases から、ライセンスビルドは clearcotelabs.com から）、使用前に SHA-256 を検証します。検証されていないものが実行されることはありません。ビルドはビルドごとにユーザーのキャッシュディレクトリ（Windows では %LOCALAPPDATA%\clearcote\Cache、Linux では ~/.cache/clearcote。場所を変えるには CLEARCOTE_CACHE を設定）にキャッシュされるため、ダウンロードはそれぞれ 1 回だけです。古いビルドは clearcote clear-cache を実行するまで残ります。

複数のプログラムで 1 つのキャッシュを共有する

キャッシュを共有するプログラムは、順番にビルドをインストールします（SDK 0.41.0+。Python、Node、.NET のいずれも同様）。最初のプログラムがダウンロードし、ほかのプログラムはその完了を待ってから使います。別のプログラムが実行中のビルドが、実行中に置き換えられることはありません。待機中のプログラムは 30 分で待つのをやめ、インストールを保持しているプロセスを示すメッセージを表示します（ロックはそのビルドのキャッシュフォルダーにある .install-lock ファイルで、いつ削除しても安全かはメッセージに示されます）。クラッシュしたプログラムが残したロックは、自動的に引き継がれます。

キャッシュ済みのビルドのファイルが破損したり削除されたりした場合（ウイルス対策ソフトによる隔離、フォルダーの削除など）は、次回の起動時に 1 回のダウンロードで修復されます。そのファイルがまだ使用中の場合は、起動がその場で停止し、そのブラウザを使っているプログラムをすべて閉じてから再試行するよう求めます。このロックが機能するには、キャッシュを共有するすべてのプロセスが SDK 0.41.0 以降で動いている必要があります。古いリリースはロックを待ちません。

Windows：環境によっては、ダウンロードしたビルドをその場所から起動できないことがあります。たとえば、パッケージ化された（MSIX）アプリの中で動くプログラムでは、%LOCALAPPDATA% への書き込みが Windows によってリダイレクトされます（起動は spawn UNKNOWN または "the side-by-side configuration is incorrect" で失敗します）。その場合、SDK はビルドのコピーを ~/.clearcote/recovered に 1 つ作り、以降は Python、Node、.NET のどこから起動してもそれを使います。そのため一時フォルダーには何も残らず、2 回目以降の起動は数秒で済みます（Python と Node は 0.40.1 から、.NET は 0.41.0 から）。clearcote clear-cache はこれらのコピーも削除します。.NET SDK にはコマンドラインがないため、そこでは WinLaunch.ClearRecovered() を呼び出してください。

SDK をアップグレードせずにオープンビルドを更新する

キーがない場合は、自動更新を有効にすると、SDK が固定しているビルドの代わりに GitHub 上の最新のオープンビルドを使えます。そのリリースの SHA256SUMS.txt と照合して検証し（gpg がインストールされていれば署名鍵とも照合します）、GitHub に接続できない場合は固定のビルドにフォールバックします。シェルからは clearcote update で同じことができます。キーがある場合は何も変わりません。すでに現行のライセンスビルドを使っているからです。

import { launch } from "clearcote";
await launch({ autoUpdate: true });   // or set env CLEARCOTE_AUTO_UPDATE=1

ブラウザ自体が外部へ勝手に通信したり、自らを更新したりすることはありません。キーがない場合、ブラウザが変わるのは SDK をバージョンアップしたときか、autoUpdate を有効にしたときだけです。キーがある場合、SDK は新しいライセンスビルドを次回の起動時に取り込みます。Pro では version でビルドを固定しておけます。

ビルドを選ぶ

version を渡します（または CLEARCOTE_BROWSER_VERSION を設定します）。指定できるのは "latest"、"154" のようなメジャーバージョン、"154.0.8037.57" のような正確なバージョン、またはライセンスビルドのリビジョン "r36" / "154.0.8037.57-r36" です。何かをダウンロードする前に、バージョンやメジャーは公開カタログと、リビジョンはライセンスサーバーと照合されます。releaseChannel: "preview"（Python では release_channel、または CLEARCOTE_RELEASE_CHANNEL=preview）を指定すると、プレビュービルドがあればそれを取得します。ライセンスビルドでは、古いビルド、バージョン固定、プレビューチャンネルは Pro の機能です。無料キーでは常に最新版が使われます。

clearcote install --version 154        # fetch + verify a build ahead of time
clearcote install --channel preview     # the newest preview build (Pro)
clearcote info                          # what's installed and cached, and your key
clearcote clear-cache                   # delete cached builds

バイナリを直接使う場合 / Docker を使う場合

• バイナリを直接使う場合（オープンビルドのみ。ライセンスビルドは SDK、clearcote serve、Docker イメージのいずれかを通じて実行します）：Releases ページから新しいアーカイブをダウンロードし、チェックサムと署名を検証して（検証を参照）、executable_path / executablePath（または CLEARCOTE_BINARY）を新しい chrome に向けます。
• Docker：docker pull teamflatearth/clearcote で最新のイメージを取得し、コンテナを作り直します。無料キーには、SDK 0.30.0 以降でビルドされたイメージが必要です。キーを使う場合は -v clearcote-cache:/opt/xdg-cache をマウントしてください。そうすれば、ライセンスビルドは新しいコンテナのたびにダウンロードされることなく、1 回のダウンロードで済みます。デプロイを参照してください。

ライセンスビルド：常に最新、しかもいち早く

ライセンスビルドは最新の Chromium と最新のパッチに追従するため、手動で再ビルドしなくても更新を受け取れます。CLEARCOTE_LICENSE_KEY を設定するか、licenseKey を渡すか、clearcote login を実行してください（Python / Node の場合。npm でローカルにインストールしたときは npx clearcote login）。このコマンドはキーを確認して ~/.clearcote/license.key に保存します。このファイルは .NET を含むすべての SDK が読み込みます。キーの入手方法は 2 つあります：

• GitHub で無料：同時に 1 つのブラウザを無料で使えます。作成から 30 日以上経った GitHub アカウントでサインインし、ダッシュボードの「Licenses」を開いて「Connect GitHub and get it free」をクリックし、続いて「Claim my free key」をクリックします（GitHub アカウント 1 つにつき 1 つ）。キーの有効期間は 30 日です。期限が切れる前に、同じページから無料で更新してください。
• Pro：同じビルドを、同時起動は最大 250 ブラウザまで使えます。古いビルド、バージョン固定、プレビューチャンネルも利用でき、オーナーによるメールサポートも付きます。

新しいメジャーバージョンは、まずライセンスビルドに届きます。新しい Chromium メジャーがビルドされると、「GitHub で無料」と Pro ではすぐに利用できます。オープンビルドにはその後で入り、目標はリリースから約 2 か月後です（現在は Chromium 150）。オープンビルドは常に完全にオープンで、再現可能です。ライセンスビルドは最新のものをより早く受け取ります。

ライセンスブラウザのカウント方法

キーを使って起動したブラウザは、それぞれライセンスサーバーからスロットを 1 つ取得し、終了時に返却します。使用中の数はダッシュボードに表示され、clearcote info でも同じ数が表示されます。

• 「GitHub で無料」はすべてのブラウザをカウントします。スロットは 1 つだけなので、最初のブラウザが終了するまで、2 つ目のブラウザは（同じプログラム内でも、別のプログラムでも、別のマシンでも）The free tier runs one browser at a time, and one is already running というエラーで拒否されます。正常に終了せずクラッシュしたブラウザのスロットは、6 分以内に解放されます。
• Pro はマシン単位でカウントし、同時に最大 250 ブラウザまで対応します。1 台のマシン上のブラウザはすべて、そのマシンのスロットを共有します。2026 年 9 月 26 日より前に開始したサブスクリプションには、これまでの上限なしの条件が引き続き適用されます。250 を超える数が必要な場合はご連絡ください。上限を引き上げます。
• 無料キーには SDK 0.30.0 以降が必要です（Python、Node、.NET）。すべてのブラウザをカウントするには、SDK が起動のたびにそれを報告し、ブラウザの実行中はライセンスを有効な状態に保つ必要があるためです。古い SDK にはアップグレード用のコマンドとともに SDK_UPGRADE_REQUIRED が返され、それでも古い SDK がエンジンまで到達した場合は、エンジン側で拒否されます。Pro キーは、これまでどおり古い SDK でも動作します。
• 無料のブラウザは、スロットがなくなると停止します。チェックは起動時だけでなく継続的に行われます。キーが失効した場合、スロットが別の場所から返却（チェックイン）された場合、またはライセンスが上限を超えた場合、すでに開いている無料のブラウザは約 2〜3 分以内に終了します。短時間のネットワーク断（ハートビートの 1〜2 回の取りこぼし）は吸収されますが、約 2〜3 分を超えて接続できない状態が続くと、同じように無料のブラウザは停止します。
• 無料キーでは常に最新ビルドが動きます。古いライセンスビルドやプレビューチャンネルを要求すると FREE_LATEST_ONLY が返されます。ビルドの固定は Pro の機能です。
• 無料キーでのダウンロード：24 時間あたり最大 10 個の異なるビルドまで。同じビルドは、何度起動しても 1 回とカウントされます。

pip install -U clearcote          # Python 0.30.0+
npm i clearcote@latest            # Node 0.30.0+
dotnet add package Clearcote      # .NET 0.30.0+

アップグレードで変わること

ほとんどの SDK リリースでは、対応が必要な変更はありません。以下のリリースは、既存の構成の動作を変えます。すべてのリリースは、ダッシュボードの「Releases」に掲載しています。

• ライセンスビルド 154 r36、既存のシード：シードは、メーカーごとに 1 つのモデルではなく、マシン自身のグラフィックスのメーカーの実在する複数のモデルからグラフィックスカードを選ぶようになりました。そのため、ほとんどのシードは r35 とは異なるカードを報告します。NVIDIA のカードを搭載したマシンでは、エントリーレベルのハードウェア（プロセッサーのスレッド数 4〜6、メモリ 4〜8 GB、小さな画面）を名乗っていたシードが、ミドルレンジ以上を名乗るようになり、そうしたマシンではタッチスクリーンを名乗るシードもありません。シードが r36 より前に持っていたアイデンティティを維持するには、persona_schema=2 / personaSchema: 2 を設定してください。別のマシンで同じシードを使う場合を参照してください。
• ライセンスビルド 154 r36、サードパーティ Cookie：古い SDK や独自のランチャーが Cookie のオプションを何も渡さない場合も含め、ブラウザは Chrome と同じくデフォルトでサードパーティ Cookie を許可するようになりました。--block-third-party-cookies でブロックできます。
• 0.42.0、Linux ホスト：Linux ペルソナの WebGL は、ヘッドレスだけでなく headed でも EGL 経由の Mesa で描画されるようになりました（ホストに libegl1 が必要です）。そのため、headed の Linux ペルソナの WebGL のレンダラー文字列、拡張機能の一覧、上限値が一度だけ変わり、ヘッドレス起動がすでに示していた、実際の Linux マシンの多くが報告するのと同じ形式になります。ウィンドウマネージャーのない Xvfb 上で headed 起動すると、ウィンドウは画面に合わせた状態で開きます。ヘッドレス起動では、ペルソナが適用されない場合でも現実的なディスプレイが保たれ、serve() では --window-position だけを渡した場合もそれが保たれます。Playwright & Puppeteer を参照してください。
• 154 r34 以降のライセンスビルド、disableGpuFingerprint：GPU が報告する内容だけを変えるようになりました。WebGL のピクセル読み出しにはシードに基づくサイトごとのノイズが残るため、readPixels と WebGL canvas の書き出しが一致します。以前は readPixels のノイズだけを止めていました。フィンガープリントフラグを参照してください。
• 0.41.1、人間らしい入力：humanize を有効にすると、スクロールは実際のホイールと同じように、マウスホイールのノッチ単位で動きます。1 ノッチあたり、Windows のアイデンティティでは 100 px、Linux では 120、macOS では 40 です。要求した距離は最も近いノッチ数に丸められる（最低 1 ノッチ）ため、mouse.wheel(0, 800) は Windows では 800 px、Linux では 840 スクロールします。また、速いキーの組み合わせでは、タイピング時に前のキーを離す前に次のキーを押すことがあるようになりました。.NET では、数値をシードにしたヒューマナイザーが、Python や Node と同じ運動特性で動くようになりました。以前は、0 以外の数値シードがすべて同じ運動特性を共有していました。人間らしい入力を参照してください。
• 0.41.0（r32 以降のライセンスビルド）：ペルソナはコマンドラインではなく環境変数経由でブラウザに渡されるため、プロセス一覧からシードを読み取っていたツールでは見つからなくなります（persona_env=False で従来の方法に戻せます）。ローカル起動で作成されるコンテキストはライトのカラースキームをエミュレートしなくなったため、ダークのペルソナはどこでもダークを報告します（固定するには color_scheme を渡します）。ペルソナを指定したヘッドレスの Linux 起動では、ペルソナが名乗るサイズの画面が割り当てられます。起動オプションを参照してください。
• 0.41.0、Linux 上の .NET：起動時に、ホストのフォントではなく、Python と Node が以前からそうしているようにブラウザに同梱のフォントを使うようになりました。そのため Linux 上の Windows ペルソナの計測値が変わり、ほかの 2 つの SDK と同じになります。Linux で独自のフォントを使うを参照してください。
• 0.41.0、Windows コンピューター上の Linux ペルソナ：SDK がプロセスごとに一度だけ警告します。Windows は GPU を Direct3D 経由で動かすため、WebGL と WebGPU の上限値に制約がかかります。ペルソナは上限値を下げることはできても、ドライバーの上限を超えて引き上げることはできないため、Windows 上の Linux ペルソナは、どの Linux マシンにもない上限値を報告してしまいます。Windows では Windows を名乗るか、Linux ペルソナは Linux 上か Docker 内で実行してください。この警告は quiet または CLEARCOTE_NO_WARN で抑制できます。
• Docker イメージ sdk-0.41.0：イメージの seccomp プロファイルを指定してコンテナを起動すれば、Chrome はサンドボックスありで動作できます。指定しなければ、コンテナはこれまでどおり動作します。各文字体系用のフォントも内蔵しています。デプロイを参照してください。
• 0.40.0：macOS では、launch() が Clearcote の Docker イメージを実行します（Docker Desktop が必要です。docker=False でオフにできます）。macOS を参照してください。

アップグレード後は再検証を

新しいビルドでは、シグナルが変わることがあります。フィンガープリントのチェック（CreepJS など）を再実行し、インポートしたプロファイルを使っている場合は、引き続き整合性を保って読み込まれることを確認してください（検証を参照）。現在のオープンビルドは v0.1.0-pre.23（Chromium 150.0.7871.114）、現在のライセンスビルドは 154.0.8037.57-r36 です。今後の予定はロードマップで確認できます。