Trình duyệt được lưu trữ sẵn (hosted)

Khởi động một trình duyệt Clearcote trên máy chủ của chúng tôi chỉ với một lệnh gọi API và điều khiển nó qua Chrome DevTools Protocol, từ Playwright, Puppeteer hoặc bất kỳ client CDP nào. Bạn không phải tự cài đặt hay vận hành gì cả. Mặc định, lưu lượng đi ra qua IP dân cư, và bạn trả tiền theo GB từ số dư trả trước.

IP dân cư, không phải datacenter. Các trang web thấy một kết nối internet gia đình thật của một nhà mạng dân dụng, không phải địa chỉ của dịch vụ hosting hay cloud.
Phần cứng thật, không phải VPS. Trình duyệt chạy trên các máy chủ vật lý chuyên dụng của chính chúng tôi, không phải trên máy ảo cloud dùng chung.

Thêm về trình duyệt hosted: một SDK cho cả local và cloud (launch(cloud=True)), lượt chạy agent (đưa vào một tác vụ, nhận về JSON), bản ghi hình và dòng thời gian sự kiện, đồng bộ cookie, secret và 2FA, và bàn giao cho người thật và webhook.

Miễn phíNhận €5 lưu lượng miễn phí khi kết nối GitHub. Không cần thẻ.

Áp dụng một lần, mỗi tài khoản GitHub chỉ nhận một lần. Tài khoản GitHub phải được tạo ít nhất 30 ngày.

Nhận €5

# Build browser automation on Clearcote hosted browsers

You are helping me write browser automation that runs on Clearcote hosted browsers: real Chromium-based browsers on Clearcote's own dedicated servers, that browse through residential IPs and present a consistent real-device fingerprint. One HTTP call starts a browser; I drive it over the Chrome DevTools Protocol with ordinary Playwright or Puppeteer. Everything you need is below. The full docs are at https://www.clearcotelabs.com/docs/hosted-browsers if something here is not enough.

## What I want

<!-- Describe the task here, e.g. "log in to my account on example.com and export the orders table to CSV every morning". -->

If the line above is still the placeholder, ask me what the script should do before you write any code.

## How to work

1. **Look at this project first.** If it already starts or connects to a browser (`chromium.launch`, `launchPersistentContext`, `puppeteer.launch`, a `connectOverCDP` / `browserWSEndpoint` to another provider, Selenium, undetected-chromedriver, …), switch that code over (see "Switching an existing setup") instead of writing a parallel script. Keep the page logic; only the browser start changes.
2. **Otherwise start a new script** in Node · Playwright unless the project clearly uses another language.
3. **API key:** read it from the environment variable `CLEARCOTE_API_KEY` (it starts with `cc_live_`, from https://www.clearcotelabs.com/dashboard/api-keys). Never hard-code it, print it or commit it; add `CLEARCOTE_API_KEY=` to `.env.example` if the project has one.
4. **Always end the session** with `browser.close()` in a `finally` block. An open session keeps a slot and keeps loading background traffic.
5. **Set `maxGb`** on the create call (e.g. `0.05` while testing) so a heavy page cannot drain the balance, then run the script once against the real site and fix what breaks.
6. Pick the session options from the table below to fit the task: usually one `identity` per account and a `country`.

## Connect

`POST https://www.clearcotelabs.com/api/v1/browsers` with `authorization: Bearer <key>` and a JSON body of options. It answers `201` with `{ id, connectUrl, expiresAt, pricing, limits }`. `connectUrl` is a single-use WebSocket URL: connect within two minutes; if the connection is refused, create a new session rather than retrying the same URL.

```javascript
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({}),
});
const { connectUrl, error } = await res.json();
if (error) throw new Error(error);

const browser = await chromium.connectOverCDP(connectUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
console.log(await page.title());
await browser.close(); // ends the session
```

- Playwright: `playwright-core` is enough (no bundled browser needed). Use the context that already exists (`browser.contexts()[0]`) instead of `browser.newContext()`.
- Puppeteer: `puppeteer-core` is enough: `puppeteer.connect({ browserWSEndpoint: connectUrl, defaultViewport: null })` (without `defaultViewport: null` Puppeteer emulates an 800x600 page inside the real window).
- Python: `p.chromium.connect_over_cdp(connect_url)`, then `browser.contexts[0]`.
- Selenium / WebDriver cannot connect; port that code to Playwright.

## Session options

All optional, sent as the JSON body of the create call.

| Field | Type | Meaning |
| --- | --- | --- |
| `identity` | string | One label per account you run: the same device fingerprint AND the same residential IP, for as long as that IP stays online. |
| `fingerprint` | string | Device seed only (no IP pinning). The same seed gives the same device profile every time; with lightStealth on it picks from a small set of metadata profiles. |
| `lightStealth` | boolean | Default true: varies only the metadata axes the host can back up. Set false to turn it off. |
| `platform` | windows | Always windows: the browsers run on Windows machines, and a persona of another system there reports GPU limits and fonts no such machine has. Another value starts a Windows session and `warnings` says so. |
| `brand` | Chrome \| Edge \| Opera \| Vivaldi | Browser brand the persona presents. |
| `timezone` | IANA name | e.g. America/New_York. Use geoip instead to follow the exit IP. |
| `locale` | string | Accept-Language, e.g. en-US,en. |
| `geoip` | boolean | Timezone and language follow the exit IP, with your own proxy or ours. Default true unless you set timezone or locale yourself. |
| `proxy` | "managed" \| { server, username?, password? } | Omitted = managed residential pool. Or your own proxy: http://, socks5:// or socks5h:// (rules below). |
| `country` | 2-letter code | Managed pool: exit country, e.g. us, de, gb. |
| `state` | region code | Managed pool: exit state/region, e.g. ca, ny. Needs country. |
| `city` | city name | Managed pool: exit city, e.g. "los angeles". Needs state. |
| `proxySession` | string | Managed pool: sticky label. The same label returns the same exit IP later (kept for 24 hours). |
| `timeoutSec` | number | Hard limit on the session length, in seconds (10 up to the account maximum below). |
| `idleTimeoutSec` | number | End the session after this long without a CDP command (10–1800). |
| `maxGb` | number | Stop the session after this much traffic (0.001–1000). |
| `headless` | boolean | Default true. |
| `humanize` | boolean | Default true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, and holds each click for a human press time. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and the wheel are left as sent. false turns it off. See "Human input". |
| `keepAlive` | boolean | Default false. Keep the browser running when your client disconnects, until you end it (DELETE, or the CDP command Browser.close) or a limit does; reconnect with POST /api/v1/browsers/<id>/connect. |
| `version` | string | Run a specific Clearcote release, e.g. "152.0.7977.82-r21" or "r21". Omitted = the current release. See "Pinning a release". |
| `profile` | "name" \| { name, persist? } | Load a saved profile (cookies + site storage). With persist: true, save it back when the session ends. See "Profiles". |
| `url` | http(s) URL | Opened in the first tab before you connect: you find it already loading. |
| `adblock` | boolean | Refuse known ad and tracker hosts before they load, so they are never billed. Default false. |
| `solveSliders` | boolean | Default true. Slide-to-verify challenges are dragged for you, in any tab or frame; false leaves them to your script. See "Slider challenges". |
| `solveCheckboxes` | boolean | Default true. "Verify you are human" checkboxes are clicked for you, in any tab or frame; false leaves them to your script. See "Checkbox challenges". |
| `challengeService` | true \| { categories?, sites?, key?, apiKey?, mode?, maxSolves?, maxSpendEur? } | Default off. Challenges the free actions cannot clear go to a solving service, with your own key or ours (billed per solve). `true` (or no `categories`) auto-selects: every challenge it recognises, in token, clearance, block-page and image; or list `categories` and `sites` yourself. See "Challenge service". |
| `record` | boolean | Default false. Record the session as an MP4; GET /api/v1/browsers/<id>/recording once it is ready (kept 14 days). |
| `note` | string | Your label for the session (at most 256 characters). Shown in the dashboard; filter by it in the list. |
| `worker` | string | Place the session on the same server as an earlier one (its `worker`). If that server is full or offline, it starts on another one and `warnings` says so. |

- **Same account, every run:** pass `identity: "<one label per account>"`. It returns the same device AND the same exit IP while that residential IP stays online. Every session still starts with an empty profile, so save cookies/storage yourself at the end (Playwright `context.storageState()`, Puppeteer `page.cookies()`) and restore them at the start.
- **Location:** `country` (e.g. `us`), then optionally `state` and `city`. Leave `geoip` on so timezone and language follow the exit IP.

## Switching an existing setup

When moving code from a local browser or another provider, replace the launch with the create call + connect above, keep the page logic, and:

- **Remove fingerprint spoofing:** stealth plugins (`puppeteer-extra-plugin-stealth`, `playwright-stealth`, …), custom user-agent strings, `navigator`/WebGL/canvas patches in init scripts, and flags like `--disable-blink-features=AutomationControlled`. The browser already presents one coherent device; overrides on top of it create mismatches that are easier to spot, not harder.
- **Map the old settings to options** instead of emulating them: a proxy → `country`/`state`/`city` on the included residential pool, or `proxy: { server: "http://host:port", username, password }` for your own (HTTP only; the other location options are then rejected). A fixed timezone or locale → `timezone` / `locale`, or better `geoip: true`. An operating-system or browser-brand choice → `platform` / `brand`. A persistent profile / `userDataDir` → `identity` plus saved cookies.
- **Drop** `headless`, executable paths, viewport / device-scale / user-agent / timezone / locale options passed to `newContext()` or `newPage()`, and window-size flags, unless the site genuinely needs a specific viewport.
- **One session per account, one account per identity.** Run several accounts in parallel as separate sessions (up to 75 at once).

## Keep traffic (and cost) down

Billing is €1.00 per GB of traffic between the browser and websites, residential proxy included. Time, sessions and CDP messages are free. A browser needs at least €0.50 of balance to start.

- Block images, media and fonts unless the site needs them: Playwright `context.route("**/*", r => ["image","media","font"].includes(r.request().resourceType()) ? r.abort() : r.continue())`; Puppeteer `page.setRequestInterception(true)` with the same check.
- Wait for `domcontentloaded` and then the one element you need, not `networkidle`.
- Reuse one session for many pages on the same site; its cache saves repeat downloads.
- Once logged in, a `fetch()` from inside the page for the JSON you need is far lighter than reloading pages.

## Limits

- 75 browsers running or starting at once; sessions last at most 4 hours; a session with no CDP command for 5 minutes closes (`idleTimeoutSec` changes it).
- Every session starts with a fresh profile that is deleted when it ends.
- No `file://`, no uploading files from the server, no private networks, no port 25.

## Errors

Errors are JSON `{ "error": "...", "code": "..." }`. Handle 402 (top up), 429 `CONCURRENCY_LIMIT` (close a session first) and 503 `NO_CAPACITY` (retry after a few seconds) in the code.

| Status | code | Meaning |
| --- | --- | --- |
| 400 | — | The body is not JSON, or an option is invalid; the message says which. |
| 400 | `UNKNOWN_VERSION` | No release matches `version`; the message lists the ones you can pick. |
| 400 | `TOO_LARGE` | The whole run configuration as stored (task, schema, sealed secrets and the browser options) is capped at 60 KB; shorten them. |
| 400 | `INVALID` | A webhook or cookie import body is invalid; the message says which field (and which cookie). |
| 400 | `TOO_MANY` | A cookie import would leave the profile with more than 5000 cookies. Use mode "replace", or import fewer. |
| 400 | `CHALLENGE_KEY_MISSING` | challengeService has no key to use: pass challengeService.apiKey, store your key in the dashboard (Settings), or use key "managed". |
| 401 | — | Missing, malformed or revoked API key. |
| 401 | `INVALID_LINK` | A share, hand-off or replay link that is invalid, of the wrong kind, or expired. |
| 403 | `SUSPENDED` | Cloud browsers are suspended for this account (no new sessions or runs); contact support@clearcotelabs.com. |
| 403 | `NOT_CONTROL` | Only a link that lets you take control can mark a hand-off done; this one is watch-only. |
| 402 | `INSUFFICIENT_BALANCE` | Balance below the minimum. Top up in the dashboard. |
| 402 | `CHALLENGE_LIMIT` | This month's challenge-service limit on our key is reached. Raise it in the dashboard (Settings), or use your own key. |
| 404 | `NOT_FOUND` | No session, run, profile, webhook or recording with that id on your account. |
| 409 | `NOT_RUNNING` | Live view, a reconnect or a hand-off asked for before the browser started or after it ended. |
| 409 | `NOT_KEEPALIVE` | This session cannot be reconnected. Start it with keepAlive: true. |
| 409 | `PROFILE_IN_USE` | Another session is already saving to that profile. Stop it, or open the profile with persist: false. |
| 409 | `NOT_READY` | The recording is still being uploaded. Try again shortly after the session ends. |
| 409 | `HANDOFF_UNSUPPORTED` | The server running this browser does not support hand-off yet. |
| 409 | `NO_HANDOFF` | Marked done, but no hand-off was asked for. |
| 409 | `HANDOFF_EXPIRED` | The hand-off timed out before it was marked done. |
| 409 | `WEBHOOK_LIMIT` | At most 5 webhooks per account. Delete one first. |
| 410 | `ENDED` | A live link whose session has ended. |
| 410 | `GONE` | A replay link whose recording is no longer available (failed, or past its retention). |
| 413 | `TOO_LARGE` | A cookie import would make the profile larger than 3.5 MB. |
| 429 | `CONCURRENCY_LIMIT` | Too many browsers running or starting at once. Close one first. |
| 429 | — | More than 60 create calls in a minute from one address. Slow down. |
| 429 | — | More than 60 cookie imports in 10 minutes on one account (or 30 new webhooks in 10 minutes, 10 webhook tests or 60 hand-off requests a minute). Wait and retry. |
| 503 | `NO_CAPACITY` | No free browser slot right now, or no server that can run what you asked for (runs, schema, secrets, recording, the challenge service). Retry after a few seconds. |
| 503 | `NO_WORKER` | The server running that session is not reachable at the moment. |
| 503 | `NOT_CONFIGURED` | Hosted browsers (or that part of them) are not configured on this server. |
| 503 | `NOT_AVAILABLE` | Notes, profiles, runs, recordings, events, hand-off, webhooks or the challenge service are not enabled on this server yet. |

## Managing sessions

- `GET https://www.clearcotelabs.com/api/v1/browsers/<id>`: status, traffic (top 20 sites by bytes), seconds and cost so far.
- `DELETE https://www.clearcotelabs.com/api/v1/browsers/<id>`: stop it.
- `GET https://www.clearcotelabs.com/api/v1/browsers`: balance and the 20 most recent sessions.
- Watch a run live and see its traffic in the dashboard: https://www.clearcotelabs.com/dashboard/browsers.

1. Lấy API key

Tạo một key trên trang “API keys”. Key bắt đầu bằng cc_live_ và được gửi dưới dạng bearer token. Hãy giữ bí mật: bất kỳ ai có key đều có thể tiêu số dư của bạn.

2. Khởi động trình duyệt và kết nối

POST /api/v1/browsers trả về một connectUrl: một URL WebSocket dùng một lần cho trình duyệt đó. Hãy kết nối trong vòng hai phút; URL này không dùng lại được. Trình duyệt khởi động ngay khi bạn kết nối, thường trong vòng vài giây, nhưng khi có country thì có thể mất tới khoảng nửa phút, vì vị trí của IP đầu ra được tra cứu trước. Mặc định Playwright ngừng chờ sau 30 giây, nên các ví dụ truyền timeout là hai phút.

javascript

// 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

javascript

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

python

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

Lệnh tạo trả về 201 kèm mọi thứ code của bạn cần để kết nối và để biết giá:

json

{
  "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
}

Các thực hành tốt nhất

Kết nối, đừng launch. Dùng connectOverCDP hoặc puppeteer.connect với connectUrl; chromium.launch() thì lại khởi động một trình duyệt trên chính máy của bạn.
Dùng những gì đã có sẵn. Lấy browser.contexts()[0] và trang đầu tiên của nó thay vì tạo context mới: context mới bắt đầu mà không có cookie và dữ liệu lưu trữ của profile, và Playwright gán cho nó một viewport giả lập 1280×720 không khớp với cửa sổ trình duyệt.
Đặt persona lúc tạo phiên, không phải từ script. Quốc gia, múi giờ và ngôn ngữ thuộc về lệnh tạo. Ghi đè user agent, viewport hay các thuộc tính navigator từ script sẽ tạo ra đúng những điểm bất nhất mà cơ chế phát hiện đang tìm.
Giữ CDP hook ở phạm vi hẹp. Listener diện rộng, việc chặn (interception) mọi request và init script chính là fingerprint riêng của automation. Playwright và Puppeteer nguyên bản vẫn chạy bình thường, trừ hai lệnh gọi (setContent và exposeFunction): engine giữ các tác dụng phụ của Runtime.enable tránh xa chính trang web, nên một driver đã được vá như Patchright chỉ là tùy chọn chứ không bắt buộc.
Một phiên, nhiều trang. Khởi động trình duyệt là phần chậm; hãy điều hướng bên trong nó. Đăng nhập một lần với một profile thay vì đăng nhập ở mỗi lần chạy.
Luôn dừng phiên. Đóng trình duyệt trong khối finally, và đặt maxGb cùng idleTimeoutSec phù hợp với công việc, để một bug không thể để trình duyệt chạy mãi và tiêu số dư của bạn.
Quan sát trước khi thêm code. Khi một site hoạt động bất thường, hãy xem nó trong live view (hoặc giành quyền điều khiển) trước khi thêm các lệnh chờ và cách xử lý tạm thời.