ホスト型ブラウザ

API を 1 回呼び出すだけで当社のサーバー上に Clearcote ブラウザを起動し、Playwright や Puppeteer、その他任意の CDP クライアントから Chrome DevTools Protocol 経由で操作できます。自分で何かをインストールしたり運用したりする必要はありません。トラフィックはデフォルトで住宅用 IP から出ていき、料金はプリペイド残高から GB 単位で支払います。

• データセンターではなく住宅用 IP。Web サイトから見えるのは、一般消費者向けプロバイダーの実在する家庭用インターネット回線であり、ホスティングやクラウドのアドレスではありません。
• VPS ではなく実機。ブラウザは共有のクラウド仮想マシンではなく、当社が所有する専用の物理サーバー上で動作します。

ホスト型ブラウザの詳細：ローカルとクラウドで同じ SDK（launch(cloud=True)）、エージェント実行（タスクを渡すと JSON が返る）、録画とイベントタイムライン、Cookie 同期、シークレット、2FA、人への引き継ぎと Webhook。

1. API キーを取得する

ダッシュボードの「API keys」ページで作成します。キーは cc_live_ で始まり、Bearer トークンとして送信します。他人に知られないようにしてください。キーを持っている人なら誰でも、あなたの残高を使えてしまいます。

2. ブラウザを起動して接続する

POST /api/v1/browsers は connectUrl を返します。これはそのブラウザ専用の、1 回限り有効な WebSocket URL です。2 分以内に接続してください。同じ URL は 2 回使えません。ブラウザは接続した時点で起動し、通常は数秒以内に立ち上がります。ただし country を指定すると、先に出口 IP の所在地を調べるため、最大で 30 秒ほどかかることがあります。Playwright はデフォルトで 30 秒経つと接続をあきらめるため、各例では 2 分の timeout を渡しています。

// Node.js + Playwright
import { chromium } from "playwright";

const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
  method: "POST",
  headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
  body: JSON.stringify({ identity: "account-1", country: "us" }),
});
const { connectUrl, id, error } = await res.json();
if (error) throw new Error(error);

const browser = await chromium.connectOverCDP(connectUrl, { timeout: 120_000 }); // the browser starts as you connect
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
await browser.close(); // ends the session

// Puppeteer: the same connectUrl
const browser = await puppeteer.connect({ browserWSEndpoint: connectUrl, defaultViewport: null });

# Python + Playwright
import requests
from playwright.sync_api import sync_playwright

r = requests.post("https://www.clearcotelabs.com/api/v1/browsers",
                  headers={"authorization": "Bearer cc_live_..."},
                  json={"identity": "account-1", "country": "de"}).json()
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(r["connectUrl"], timeout=120_000)
    page = browser.contexts[0].new_page()
    page.goto("https://example.com")
    browser.close()

作成リクエストは 201 を返します。レスポンスには、接続と料金の把握に必要な情報がすべて含まれています。

{
  "id": "bs_…",                       // use it with GET / DELETE /api/v1/browsers/<id>
  "connectUrl": "wss://…/v1/connect/bs_…?token=…",
  "expiresAt": "2026-09-24T10:02:00.000Z", // connect before this (two minutes)
  "worker": "w_…",
  "pricing": { "eurPerGb": 1, "eurPerHour": 0 },
  "limits": { "maxSeconds": 14400, "idleSeconds": 300 } // plus maxBytes when capped
}

ベストプラクティス

1. 起動するのではなく接続する。connectUrl を指定して connectOverCDP または puppeteer.connect を使ってください。chromium.launch() では、手元のマシンでブラウザが起動してしまいます。
2. 既存のものを使う。新しいコンテキストを作らずに、browser.contexts()[0] とその最初のページを使ってください。新しいコンテキストはプロファイルの Cookie やストレージなしで始まり、しかも Playwright はブラウザウィンドウと一致しない 1280×720 のエミュレートされたビューポートを割り当てます。
3. ペルソナはスクリプトからではなく作成時に設定する。国、タイムゾーン、言語は作成リクエストで指定します。スクリプトからユーザーエージェント、ビューポート、navigator のプロパティを上書きすると、検知が探しているまさにその不整合を生んでしまいます。
4. CDP フックは最小限にする。広範なリスナー、全リクエストのインターセプト、初期化スクリプトは、それ自体が自動化のフィンガープリントになります。標準の Playwright と Puppeteer は、2 つの呼び出し（setContent と exposeFunction）を除けばそのままで動作します。エンジンが Runtime.enable の副作用をページ自体から切り離しているため、Patchright のようなパッチ適用済みドライバーは必須ではなく任意です。
5. 1 つのセッションで多くのページを。時間がかかるのはブラウザの起動なので、起動したブラウザの中でページを移動してください。ログインは実行のたびに行うのではなく、プロファイルを使って一度だけ行います。
6. 必ず停止する。finally でブラウザを閉じ、ジョブに合わせて maxGb と idleTimeoutSec を設定してください。そうすれば、バグがあってもブラウザが残高を消費しながら動き続けることはありません。
7. コードを足す前に様子を見る。サイトの挙動がおかしいときは、待機処理やワークアラウンドを追加する前に、ライブビューで様子を見てください（または操作を引き継いでください）。