デプロイ — Docker と CDP エンドポイント

Clearcote を常駐の CDP エンドポイントとして動かし、既存のフレームワーク（Playwright、Puppeteer、browser-use、Crawl4AI、Stagehand など）の接続先をそこに向けるだけで使えます。コードの変更は不要です。バイナリを直接起動する（--enable-automation なし）ので、navigator.webdriver は false のままです。仕組みからしてステルスです。

公式 Docker イメージ

イメージを pull すればすぐに使えます。CDP クライアントは公開したポート経由で接続します。

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.contexts[0].new_page()                            # the container's own profile
    page.goto("https://example.com")
    print(page.title())

イメージには、SHA-256 で検証済みの Linux 向けオープンビルドと、Windows フォントとメトリック互換のフォントが組み込まれています（そのため、ラテン文字のテキストはペルソナのフォントと同じ寸法で計測されます。ただしオープンビルドのフォントバンドルには CJK の書体がないため、中国語・日本語・韓国語のテキストは、書体を同梱したライセンスビルドを使うまで、対応するフォントなしで描画されます）。デフォルトのペルソナは、整合性のあるネイティブ Linux です。ブラウザは仮想ディスプレイ上で headed モードで動作します（純粋なヘッドレスにするには CC_HEADLESS=1）。設定はすべて環境変数で行います。

docker run -d -p 127.0.0.1:9222:9222 -e CC_PLATFORM=linux -e CC_FINGERPRINT=user-7423 -e CC_ACCEPT_LANGUAGE=en-US -e CC_TIMEZONE=America/New_York teamflatearth/clearcote

コンテナが実際に動いている OS を名乗ってください。ページが読み取れる情報の一部はブラウザの下にあるホスト OS から来ており、ペルソナの設定はそこまで届きません。この Linux イメージでは、CC_PLATFORM の値にかかわらず、テキストのサイズは Linux の FreeType スケーラーで決まり、フォントは fontconfig から供給されます。このイメージで CC_PLATFORM=windows として計測したところ、フォントサイズを 0.01 px ずつ変えたときにテキスト幅が変わったのは 66% のステップでした（実際の Windows 版 Chrome では 99%）。また、Segoe UI と Georgia は計測上はインストール済みに見えるものの、名前を指定して読み込むことはできません。フィンガープリントテストはこの両方を検出します。デフォルトの Linux ペルソナは問題なく通ります。Windows のアイデンティティが必要なら、Windows ビルドを使うか、Windows マシン上で動くホスト型ブラウザを使ってください。Linux サーバー上の serve() や launch() にも同じことが当てはまります。詳細：ユーザーエージェントの下にあるフォントスタック

Docker でライセンスビルドを使う — キーを渡し、キャッシュをマウントする

イメージにはオープンビルドが組み込まれています。CLEARCOTE_LICENSE_KEY を設定すると、コンテナは代わりにライセンスビルドを使います。使われるのは最新のビルドで、Pro プランなら CC_VERSION で特定のビルドを指定できます。無料キーでは常に最新のビルドが動作し、バージョンの固定は拒否されます。

docker run -d -p 127.0.0.1:9222:9222 -v clearcote-cache:/opt/xdg-cache -e CLEARCOTE_LICENSE_KEY=cc_lic_... teamflatearth/clearcote

# Pro only: pin a major, an exact build, or a revision
#   -e CC_VERSION=153        -e CC_VERSION=153.0.8010.36        -e CC_VERSION=r28

キャッシュボリュームは必ずマウントしてください。ライセンスビルドのコンテナは、初回起動時にエンジンをダウンロードします。永続化したボリュームがないと、すべてのコンテナが毎回ダウンロードし直します。ボリュームがあれば、2 回目以降のコンテナはキャッシュ済みのビルドから起動します。

起動ログにどのエンジンが使われたかが表示されるので、キーの設定ミスには、最初のリクエストがブロックされた時点ではなく、起動直後に気づけます。

[clearcote] engine: /opt/xdg-cache/clearcote/pro-153.0.8010.36-r28/browser/chrome (licensed)
[clearcote] licence lease acquired

SDK 0.26.1 以降でビルドしたイメージが必要です。GitHub で取得した無料キーの場合は 0.30.0 以降が必要です。ライセンスビルドのブラウザは、無料キーのコンテナが実行中もライセンスを最新の状態に保つことを前提としており、それより古いイメージは拒否します。以前に公開された古いイメージはキーを無視し、黙ってオープンビルドを提供します。docker pull teamflatearth/clearcote で更新してください。ライセンスビルドの実行では、起動時に同時実行数のリースも取得するため、コンテナからライセンス API へのアウトバウンド通信が必要です。リースの取得に失敗すると、コンテナは動作できないエンジンを起動するのではなく、理由を表示して終了します。無料キーでは、すべてのコンテナを通じて同時に動かせるブラウザは 1 つです。ライセンスブラウザの数え方を参照してください。

セキュリティ：CDP エンドポイントはブラウザを完全に制御できます。信頼できるネットワークにだけ公開してください。-p 127.0.0.1:9222:9222 ならホスト内に限定されます。docker/ Dockerfile は監査可能です。自分で再ビルドして検証してください。

SDK から常駐 CDP エンドポイントを立てる — serve()

バイナリを自分で起動し、どのクライアントからでも接続できる cdp_url を取得します。イメージと同じステルスな直接起動を、自分のプロセスから行えます。

from clearcote import serve

srv = serve(fingerprint="seed-123", platform="windows")   # -> srv.cdp_url
# attach ANY CDP client:
#   playwright:  p.chromium.connect_over_cdp(srv.cdp_url)
#   puppeteer:   puppeteer.connect({ browserURL: srv.cdp_url, defaultViewport: null })
#   browser-use / Crawl4AI / Stagehand: point them at srv.cdp_url
srv.close()

import { serve } from "clearcote";
const srv = await serve({ fingerprint: "seed-123", platform: "windows" });
// srv.cdpUrl -> connectOverCDP / puppeteer.connect({ browserURL, defaultViewport: null })
await srv.close();

ヘッドレスの場合、提供されるブラウザには実寸のディスプレイ（ペルソナのもの、または実際のデスクトップから抽出したもの）が割り当てられ、クライアントが接続する前にウィンドウが作業領域に合わせられます。そのため、どのページ、タブ、ポップアップも、画面に収まるウィンドウを報告します（SDK 0.31+）。ウィンドウを小さくしたい場合は windowSize: { width, height }（Python では window_size、.NET では WindowSize）を渡してください。自分で制御したい場合は、args に独自の --window-size を渡します。

1 つのエンドポイントで複数のアイデンティティ — clearcote serve

シェルからは（Python と Node のパッケージ、0.29+）、clearcote serve で常駐エンドポイントを動かせます。このエンドポイントは、接続が要求するアイデンティティごとに別々のブラウザを起動します。シード、プロキシ、タイムゾーン、言語は接続 URL から取得します。同じシードなら、起動中のブラウザを再利用します。

clearcote serve --port 9222 --idle-timeout 300 --max-browsers 16

# then, from any Playwright client:
#   chromium.connect_over_cdp("http://127.0.0.1:9222?fingerprint=acct-1&platform=windows")
#   chromium.connect_over_cdp("http://127.0.0.1:9222?fingerprint=acct-2&proxy=socks5://user:pass@host:1080&geoip=true")
#   (a password-protected proxy needs the licensed build)

デフォルトでは localhost にバインドし、Web ページから発行されうるリクエストは拒否します。アイドル状態のアイデンティティは --idle-timeout 秒後に閉じられ、--max-browsers で同時に動かす数の上限を設定できます（上限を超えたアイデンティティには HTTP 429 が返ります）。--data-dir を使うと再起動をまたいで各アイデンティティのプロファイルが保持され、--allow-host / --allow-origin を使うとリバースプロキシの背後で動かせます。http://127.0.0.1:9222/ を開くと、動作中のものを確認できます。「GitHub で無料」のキーでは、同時に動くブラウザは 1 つだけです。以前の単一アイデンティティ用スクリプト clearcote-serve --port 9222 --fingerprint seed-123 も、引き続き Python パッケージに含まれています。

直接起動 — SDK なしでオープンビルドを使う

Releases ページにあるオープンビルドは素の Chromium バイナリなので、executable_path とスイッチを指定して自分で起動できます。ライセンスビルドには、ライセンストークンを保持する SDK が必要です。以下の追加引数は、Windows 上でこのシードに対して SDK が付与する主なデフォルトです（SDK はさらに feature フラグをマージし、プロキシ経由の場合は QUIC をオフにします）。

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(
        executable_path=r"C:\clearcote\chrome.exe",
        ignore_default_args=["--enable-automation", "--enable-unsafe-swiftshader"],
        args=[
            "--fingerprint=seed-123",
            "--fingerprint-platform=windows",
            "--fingerprint-brand=chrome",
            "--accept-lang=en-US,en",
            "--lang=en-US",
            "--timezone=America/New_York",
            "--webrtc-ip-handling-policy=disable_non_proxied_udp",
            "--ignore-gpu-blocklist",
        ],
    )
    browser.new_page().goto("https://example.com")

独自のイメージをビルドする（SDK ベース）

Clearcote は Linux x64 のバイナリを提供しているので、コンテナ内でヘッドレスで動かせます。イメージには、ブラウザのランタイムライブラリ、fontconfig、SDK が必要です。ブラウザはシステムフォントではなく、リリースに同梱のフォントバンドルを使います。公式イメージと同じく、オープンビルドには CJK の書体がありません（ライセンスビルドのバンドルには含まれています）。Linux では、ペルソナはデフォルトで整合性のあるネイティブ Linux のアイデンティティになります。WebRTC の漏洩対策はデフォルトで有効で、Privacy Sandbox の API は Google Chrome と同じく有効のままです。

FROM node:22-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      xz-utils libnss3 libnspr4 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
      libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libxfixes3 libxext6 libxrender1 \
      libpango-1.0-0 libcairo2 libx11-6 libxcb1 libexpat1 libdbus-1-3 ca-certificates \
      fontconfig fonts-liberation fonts-noto-color-emoji fonts-unifont fonts-ipafont-gothic fonts-wqy-zenhei \
 && rm -rf /var/lib/apt/lists/*
WORKDIR /app
RUN npm i clearcote
RUN node --input-type=module -e "import { download } from 'clearcote'; await download();"   # bake the binary in
COPY run.mjs .
CMD ["node", "run.mjs"]

import { launchPersistentContext } from "clearcote";
const ctx = await launchPersistentContext("/tmp/prof", {
  headless: true,
  fingerprint: "user-1",
  proxy: { server: "http://gateway:8080", username: "u", password: "p" },
  geoip: true,      // timezone + languages + WebRTC IP matched to the proxy exit
  humanize: true,   // trusted bezier input; navigator.webdriver stays false
  args: ["--no-sandbox"],
});
const page = ctx.pages()[0] ?? (await ctx.newPage());
await page.goto("https://example.com");
await ctx.close();

重いページで /dev/shm が原因のクラッシュが起きないよう、コンテナは --shm-size=1g を付けて実行してください。Python でもまったく同じです（from clearcote import launch_persistent_context、オプションは snake_case）。

CDP で接続できるもの

代わりに AI エージェントに操作させたい場合は、MCP サーバーを参照してください。直接起動のほうがステルス性が高い理由は、検知の仕組みで解説しています。