Triển khai — Docker & endpoint CDP

Chạy Clearcote như một endpoint CDP thường trực và trỏ bất kỳ framework nào bạn đang dùng vào đó — Playwright, Puppeteer, browser-use, Crawl4AI, Stagehand — mà không cần sửa code. Nó khởi chạy binary trực tiếp (không có --enable-automation), nên navigator.webdriver vẫn là false: kín đáo ngay từ cách thiết kế.

Image Docker chính thức

Pull image về là dùng được ngay. Mọi client CDP đều kết nối qua cổng được mở ra.

docker run -d --rm -p 127.0.0.1:9222:9222 -e CC_FINGERPRINT=user-7423 teamflatearth/clearcote   # CDP on http://localhost:9222

Lệnh trên chạy Chrome không có sandbox, giống như mọi image trước sdk-0.41.0. Thêm seccomp profile của image và Chrome sẽ chạy có sandbox; xem sandbox của Chrome bên dưới.

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

Image được đóng gói sẵn bản build mở cho Linux đã xác minh SHA-256, các font metric-clone của Windows (để chữ Latin có kích thước đo được giống font của persona) và, từ sdk-0.41.0, font cho các hệ chữ viết khác mà một máy Windows vẽ được ngay từ đầu (xem Font), và mặc định dùng một persona Linux native nhất quán. Trình duyệt chạy headed trên một màn hình ảo (CC_HEADLESS=1 nếu muốn headless thuần). Khi container không có GPU, WebGL được render bằng phần mềm qua backend có giới hạn khớp với GPU mà persona khai báo: Mesa cho persona Linux, dù headed hay headless, và SwiftShader cho persona Windows. Mọi cấu hình đều thực hiện qua biến môi trường:

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

Hãy khai báo đúng hệ điều hành mà container đang chạy. Một phần những gì trang web đọc được đến từ hệ điều hành host bên dưới trình duyệt, và không thiết lập persona nào chạm tới được phần đó. Trong image Linux này, chữ được tính kích thước bằng bộ scaler FreeType của Linux và font lấy từ fontconfig, bất kể CC_PLATFORM ghi gì. Đo trên image này với CC_PLATFORM=windows: tăng cỡ chữ từng bước 0.01 px làm thay đổi độ rộng văn bản ở 66% số bước (Chrome thật trên Windows: 99%), còn Segoe UI và Georgia được đo như đã cài nhưng không thể nạp theo tên. Bài kiểm tra fingerprint gắn cờ cả hai điểm này. Persona Linux mặc định thì đạt. Các font Windows thật được mount bằng CLEARCOTE_FONT_DIRS sẽ sửa được phần tên trên bản build có giấy phép từ r32 (Font), nhưng không sửa được bộ scaler, thứ mà không thiết lập nào chạm tới. Nếu cần danh tính Windows, hãy chạy bản build cho Windows hoặc dùng trình duyệt được lưu trữ sẵn (hosted), vốn chạy trên máy Windows. Điều tương tự cũng áp dụng cho serve() và launch() trên máy chủ Linux. Chi tiết: font stack bên dưới user agent.

Bản build có giấy phép trong Docker — truyền khóa, mount cache

Image có sẵn bản build mở bên trong. Đặt CLEARCOTE_LICENSE_KEY và container sẽ dùng bản build có giấy phép thay thế — bản mới nhất, hoặc với gói Pro là một bản cụ thể qua CC_VERSION. Khóa miễn phí luôn chạy bản build mới nhất, và việc cố định phiên bản sẽ bị từ chối.

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=154        -e CC_VERSION=154.0.8037.57        -e CC_VERSION=r36

Luôn mount volume cache. Container có giấy phép sẽ tải engine về ở lần khởi động đầu tiên; nếu không có volume được lưu giữ, mọi container đều phải tải lại. Có volume, các container sau sẽ khởi động từ bản build đã cache.

Log khởi động cho bạn biết mình đang dùng engine nào, nhờ vậy một khóa cấu hình sai sẽ lộ ra ngay, thay vì đến request bị chặn đầu tiên mới biết:

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

Yêu cầu image được build từ SDK 0.26.1 trở lên, và 0.30.0 trở lên nếu dùng khóa miễn phí từ GitHub — trình duyệt có giấy phép yêu cầu container miễn phí liên tục gia hạn giấy phép trong khi chạy, và sẽ từ chối image cũ hơn. Các image cũ đã phát hành sẽ bỏ qua khóa và lặng lẽ chạy bản build mở — chạy docker pull teamflatearth/clearcote để cập nhật. Một lần chạy có giấy phép cũng phải lấy một concurrency lease (suất chạy đồng thời) lúc khởi động, nên container cần truy cập ra ngoài tới API giấy phép; nếu không lấy được lease, container sẽ thoát kèm lý do thay vì khởi động một engine không thể chạy. Một khóa miễn phí chỉ chạy một trình duyệt tại một thời điểm trên tất cả container của bạn — xem cách tính số trình duyệt có giấy phép.

Từ image sdk-0.40.0, khi nhiều container có giấy phép cùng khởi động một lúc trên cùng một volume cache, engine chỉ được tải về một lần: container đầu tiên tải về, các container còn lại chờ nó.

Không để lộ thông tin bí mật qua docker inspect

Mọi biến -e đều là một phần cấu hình của container, nên bất kỳ ai chạy được docker inspect trên container đó (hoặc đọc được docker compose config, hay phần lớn các dashboard quản lý container) đều thấy CLEARCOTE_LICENSE_KEY và mật khẩu trong URL CC_PROXY ở dạng văn bản thuần. Từ image sdk-0.40.0, bạn có thể truyền chúng qua một file thay vào đó: một file JSON bên trong container, được chỉ định bằng CC_SECRETS_FILE, mà container đọc một lần khi khởi động rồi xóa đi. File phải thuộc sở hữu của user trong image (uid 10001).

printf '{"CLEARCOTE_LICENSE_KEY": "%s"}' "$CLEARCOTE_LICENSE_KEY" > clearcote-secrets.json
tar --owner=10001 --group=10001 --mode=600 -cf clearcote-secrets.tar clearcote-secrets.json
id=$(docker create -p 127.0.0.1:9222:9222 -e CC_SECRETS_FILE=/tmp/clearcote-secrets.json   -v clearcote-cache:/opt/xdg-cache teamflatearth/clearcote)
docker cp - "$id:/tmp" < clearcote-secrets.tar    # copy the file in before the container starts
docker start "$id"
rm clearcote-secrets.json clearcote-secrets.tar

Các SDK cũng làm đúng như vậy khi khởi chạy trên macOS. Bất kỳ ai có quyền truy cập Docker daemon vẫn đọc được file và bộ nhớ của một container đang chạy, nên hãy coi quyền truy cập daemon tương đương với quyền truy cập khóa.

Từ sdk-0.40.0, image chạy tini làm tiến trình init, nên các tiến trình phụ của trình duyệt đã thoát bên trong container (ví dụ từ những script bạn chạy bằng docker exec và tự khởi động trình duyệt riêng) sẽ được dọn dẹp thay vì tích tụ lại. docker stop vẫn tới được trình duyệt và giải phóng suất giấy phép.

Font

Trình duyệt chỉ thấy các font mà SDK trỏ nó tới: các font Windows thay thế đi kèm bản phát hành, sau đó là các thư mục dưới đây. Không thứ gì khác trong /usr/share/fonts đến được trình duyệt, nên một font được cài trong image không bao giờ có thể làm thay đổi độ rộng mà persona Windows báo. Từ image sdk-0.41.0:

• Font cho các hệ chữ viết được tích hợp sẵn. Emoji màu, tiếng Trung, tiếng Nhật và tiếng Hàn (WenQuanYi Zen Hei, IPA Gothic), và các font Noto cho chữ Ả Rập, Armenia, Bengal, Cherokee, Devanagari, Ethiopia, Gruzia, Gujarat, Gurmukhi, Kannada, Khmer, Lào, Malayalam, Myanmar, Sinhala, Tamil, Telugu, Thái, Tây Tạng và nhiều hệ chữ khác, nằm trong /usr/local/share/clearcote/fonts, thư mục mà CLEARCOTE_FALLBACK_FONT_DIRS liệt kê sau bộ font đi kèm. Chúng chỉ được dùng cho những ký tự mà bộ font đi kèm không vẽ được, nhờ vậy các ký tự đó hiển thị đúng thay vì thành ô trống, trên cả bản build mở lẫn bản build có giấy phép. Không có họ font Latin nào được thêm vào.
• Font của riêng bạn. Mount một thư mục chứa font, thường là bản sao thư mục C:\Windows\Fonts của một máy Windows, và chỉ định nó trong CLEARCOTE_FONT_DIRS. Thư mục này được liệt kê trước bộ font đi kèm. Trên bản build có giấy phép từ r32, mọi họ font mà nó cung cấp đều được render đúng là chính nó, dưới tên riêng của nó, và Helvetica, Times, Courier cùng các họ generic của CSS cũng đi theo; các engine cũ hơn vẫn giữ font thay thế và chỉ dùng thư mục này cho những ký tự không font nào khác hỗ trợ. Chỉ dùng những font mà bạn có giấy phép sử dụng. Thiết lập tương ứng bên ngoài Docker là fontDirs của SDK.

docker run -d -p 127.0.0.1:9222:9222 -v /srv/windows-fonts:/fonts:ro -e CLEARCOTE_FONT_DIRS=/fonts \
  -e CC_PLATFORM=windows -v clearcote-cache:/opt/xdg-cache -e CLEARCOTE_LICENSE_KEY=cc_lic_... teamflatearth/clearcote
docker exec <container> clearcote info --quick   # which writing systems render, which families are genuine

Bảo mật: endpoint CDP đồng nghĩa với toàn quyền điều khiển trình duyệt. Chỉ công khai nó trong mạng tin cậy — -p 127.0.0.1:9222:9222 giữ nó chỉ truy cập được từ máy host. docker/ Dockerfile có thể audit được — hãy tự build lại và xác minh.

Sandbox của Chrome

Sandbox Linux của Chrome chạy mọi renderer (tiến trình phân tích và chạy một trang) trong các namespace riêng, dưới một bộ lọc seccomp, nên một trang chiếm được quyền kiểm soát renderer của nó vẫn bị giới hạn trong renderer đó. Với --no-sandbox, renderer đó có mọi thứ mà user của container có: file, mạng và các tiến trình khác của user đó. Seccomp profile mặc định của Docker từ chối các lệnh gọi tạo ra những namespace đó, nên các image trước sdk-0.41.0 luôn chạy Chrome với --no-sandbox.

Từ image sdk-0.41.0, container sẽ kiểm tra trước: nó thực hiện đúng các lệnh gọi mà sandbox của Chrome thực hiện, và chạy Chrome có sandbox khi các lệnh gọi đó thành công. Hãy khởi động nó với seccomp profile đi kèm image, tức là profile mặc định của Docker được thêm hai lệnh gọi namespace mà Chrome cần:

# copy the profile out of the image (--tmpfs keeps docker from first copying the engine into a volume)
docker run --rm --tmpfs /opt/xdg-cache --entrypoint cat teamflatearth/clearcote /etc/clearcote/seccomp.json > clearcote-seccomp.json
docker run -d -p 127.0.0.1:9222:9222 --security-opt seccomp=clearcote-seccomp.json teamflatearth/clearcote

# docker compose
services:
  clearcote:
    image: teamflatearth/clearcote
    ports: ["127.0.0.1:9222:9222"]
    security_opt: ["seccomp=./clearcote-seccomp.json"]

• Log cho biết kết quả: [clearcote] sandbox: on (…), hoặc [clearcote] sandbox: OFF, Chrome runs with --no-sandbox: … kèm lý do và cách bật nó lên. Dòng serve-state có "sandbox": true hoặc false. Không có profile, container chạy y hệt như trước.
• Nó còn cần user riêng của image (không phải --user 0), CAP_SYS_CHROOT (được cấp theo mặc định; thêm lại --cap-add SYS_CHROOT sau --cap-drop ALL), một host cho phép user namespace không đặc quyền, và một máy amd64. Khi thiếu một trong các điều kiện này, container sẽ quay về --no-sandbox và cho biết lý do.
• Sự đánh đổi: với profile này, bất kỳ tiến trình nào trong container, không chỉ Chrome, đều có thể tạo một user namespace với network namespace riêng, thứ chạm tới mã mạng của kernel mà profile mặc định của Docker giữ ngoài tầm với. Các renderer của Chrome, nơi các trang không đáng tin cậy chạy, vẫn nằm dưới bộ lọc riêng của Chrome. Không có sandbox, một renderer bị chiếm quyền có mọi thứ mà user của container có, nên profile này vẫn là lựa chọn tốt hơn. Đừng dùng --privileged, --cap-add SYS_ADMIN hoặc seccomp=unconfined thay thế: chúng tắt đi nhiều lớp bảo vệ của container hơn rất nhiều.
• CC_EXTRA_ARGS=--no-sandbox tắt nó một cách có chủ đích. --no-zygote, --disable-namespace-sandbox, --renderer-cmd-prefix= và canvas bridge (--canvas-bridge-url=) cũng tắt nó, vì Chrome không thể chạy sandbox cùng với chúng ở đây.
• Cách khởi chạy trên macOS của các SDK tự truyền profile này, trên một Docker chạy trên CPU x86_64. Trên Apple silicon, image chạy ở chế độ giả lập, và sandbox tạm thời vẫn tắt ở đó.

Endpoint CDP thường trực từ SDK — serve()

Tự khởi chạy binary và nhận một cdp_url để bất kỳ client nào cũng kết nối vào được. Vẫn là kiểu khởi chạy trực tiếp kín đáo như image, nhưng được điều khiển từ chính tiến trình của bạn.

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

Khi chạy headless, trình duyệt được serve sẽ có một màn hình kích thước thật — của persona, hoặc lấy từ các máy desktop thật — và cửa sổ được căn vừa vùng làm việc trước khi bất kỳ client nào kết nối, nên mọi trang, tab và popup đều báo cáo một cửa sổ vừa với màn hình của nó (SDK 0.31+). Truyền windowSize: { width, height } (window_size trong Python, WindowSize trong .NET) để có cửa sổ nhỏ hơn, hoặc tự đặt --window-size trong args để tự kiểm soát hoàn toàn.

Một endpoint, nhiều danh tính — clearcote serve

Từ shell (gói Python và Node, 0.29+), clearcote serve chạy một endpoint thường trực, khởi động một trình duyệt riêng cho mỗi danh tính mà một kết nối yêu cầu — seed, proxy, múi giờ và ngôn ngữ lấy từ URL kết nối. Cùng một seed sẽ dùng lại trình duyệt đang chạy của seed đó.

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)

Mặc định nó chỉ bind vào localhost và từ chối những request mà một trang web có thể tạo ra. Danh tính nhàn rỗi sẽ bị đóng sau --idle-timeout giây, --max-browsers giới hạn số trình duyệt chạy cùng lúc (các danh tính tiếp theo sẽ nhận HTTP 429), --data-dir giữ profile của từng danh tính qua các lần khởi động lại, còn --allow-host / --allow-origin cho phép chạy sau reverse proxy. Mở http://127.0.0.1:9222/ để xem những gì đang chạy. Với khóa Miễn phí với GitHub, mỗi lúc chỉ chạy được một trình duyệt. Script đơn danh tính cũ clearcote-serve --port 9222 --fingerprint seed-123 vẫn còn trong gói Python.

Trực tiếp — bản build mở, không dùng SDK

Bản build mở trên trang Releases là một binary Chromium thuần mà bạn có thể tự khởi chạy bằng executable_path và các switch. Bản build có giấy phép cần SDK, nơi giữ token giấy phép của nó. Các tham số bổ sung dưới đây là những giá trị mặc định chính mà SDK thêm vào cho seed này trên Windows (SDK còn gộp thêm các feature flag và, khi dùng proxy, tắt 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")

Tự build image (dùng SDK)

Clearcote có sẵn binary Linux x64, nên chạy headless được trong container. Image cần các thư viện runtime của trình duyệt, fontconfig và SDK. Trình duyệt dùng bộ font đi kèm bản phát hành của nó thay vì font hệ thống, nên các font bạn cài bằng apt vẫn vô hình với nó cho đến khi bạn liệt kê chúng: hãy link các font chữ viết vào một thư mục và chỉ định nó trong CLEARCOTE_FALLBACK_FONT_DIRS (SDK 0.41.0+), như image chính thức làm, hoặc đặt font của riêng bạn trong CLEARCOTE_FONT_DIRS (xem Font). Đừng bao giờ liệt kê toàn bộ /usr/share/fonts: các họ font Latin trong đó sẽ làm thay đổi độ rộng của persona Windows. Trên Linux, persona mặc định là một danh tính Linux native nhất quán. Cơ chế chống rò rỉ WebRTC được bật theo mặc định; các API Privacy Sandbox vẫn bật, như trong Google Chrome. Khi đã cài libegl1 và libgl1-mesa-dri, SDK sẽ render WebGL của persona Linux qua Mesa trên EGL, với các giới hạn và dạng renderer mà máy Linux thật báo về: headless từ SDK 0.39.0, và cả headed từ 0.42.0, nên cả hai chế độ đều cho thấy cùng một bề mặt WebGL. Nếu thiếu chúng, WebGL sẽ quay về SwiftShader. Khởi chạy headed dưới Xvfb, không có trình quản lý cửa sổ, sẽ có cửa sổ được chỉnh vừa với màn hình trước khi mở trang đầu tiên (SDK 0.42.0).

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 libegl1 libgl1-mesa-dri \
      fontconfig fonts-noto-color-emoji fonts-ipafont-gothic fonts-wqy-zenhei \
 && F=/usr/local/share/clearcote/fonts && mkdir -p $F && cd /usr/share/fonts \
 && cp -l truetype/noto/NotoColorEmoji.ttf truetype/wqy/wqy-zenhei.ttc opentype/ipafont-gothic/ipag.ttf $F/ \
 && rm -rf /var/lib/apt/lists/*
# emoji + CJK, used only where the bundle has no glyph
ENV CLEARCOTE_FALLBACK_FONT_DIRS=/usr/local/share/clearcote/fonts
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();

Chạy container với --shm-size=1g để tránh crash do /dev/shm trên các trang nặng. Với Python thì y hệt (from clearcote import launch_persistent_context, các tùy chọn dạng snake_case).

Những gì kết nối được qua CDP

Muốn để một AI agent điều khiển thay bạn? Xem MCP server. Tò mò vì sao khởi chạy trực tiếp lại kín đáo hơn? Xem Cơ chế phát hiện hoạt động ra sao.