Frameworks und der Playground
Hinweise, wie Sie bestimmte Frameworks mit einem gehosteten Browser verbinden, und der Playground im Dashboard, in dem Sie eine Aufgabe oder ein Skript ausprobieren und dabei die Live-Ansicht verfolgen.
Frameworks
Alles, was sich per CDP an Chrome anhängt, funktioniert mit der connectUrl. Sie gilt nur einmal; ein Framework, das sich selbstständig neu verbindet, braucht daher für jede Verbindung eine neue Session. Der Browser startet, wenn Sie sich verbinden, meist innerhalb weniger Sekunden (siehe den Hinweis zum Timeout oben); vorher muss kein Status abgefragt werden.
// Patchright (optional; a Playwright fork): npm i patchright
import { chromium } from "patchright";
const browser = await chromium.connectOverCDP(connectUrl, { timeout: 120_000 });
const page = browser.contexts()[0].pages()[0];# Browser Use
from browser_use import Agent, Browser
agent = Agent(task="Find the cheapest flight to Lisbon next Friday", llm=llm, browser=Browser(cdp_url=connect_url))
await agent.run()
# Crawl4AI
from crawl4ai import AsyncWebCrawler, BrowserConfig
config = BrowserConfig(browser_mode="custom", cdp_url=connect_url, use_managed_browser=True)
async with AsyncWebCrawler(config=config) as crawler:
result = await crawler.arun("https://example.com")// Stagehand v4
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
const stagehand = await Stagehand.create({ browser: await localBrowser.connect({ cdpUrl: connectUrl }) });setContent und exposeFunction
Die Engine sendet nie Console-Events an den Client, denn Seiten, die nach einem Automatisierungs-Client suchen, messen genau diese Weiterleitung. Gehostete Browser bleiben dabei: Die SDK-Option stock_runtime, die sie für einen Debugging-Lauf auf Ihrem eigenen Rechner oder in Docker wieder einschaltet, wird bei einem Cloud-Launch nicht angewendet. Zwei Treiberaufrufe hängen davon ab:
page.setContent()von Playwright wartet auf ein Console-Event, das nie eintrifft, und läuft deshalb in einen Timeout (in Puppeteer funktioniert der Aufruf). Öffnen Sie das HTML stattdessen alsdata:-URL, oder schreiben Sie es selbst in die Seite, wie unten gezeigt.exposeFunction()undexposeBinding()funktionieren in Playwright und Puppeteer in der Seite, die beim Aufruf geöffnet ist, und verschwinden, sobald diese Seite navigiert. Rufen Sie sie nach der letzten Navigation auf, oder geben Sie Ergebnisse stattdessen überevaluatezurück.
// Instead of await page.setContent(html):
// Short HTML: a data: URL (the page gets no origin of its own, so no cookies or storage)
await page.goto("data:text/html," + encodeURIComponent(html));
// Any HTML: write it into a page you have navigated to; it keeps that page's origin
await page.evaluate((html) => {
document.open();
document.write(html);
document.close();
}, html);# Instead of page.set_content(html):
from urllib.parse import quote
page.goto("data:text/html," + quote(html))
# or
page.evaluate("html => { document.open(); document.write(html); document.close(); }", html)Ein Helper als Ausgangspunkt
Anlegen mit den Retries von oben, verbinden und immer stoppen – alles in einer Funktion:
// clearcote-hosted.ts
import { chromium, type Browser } from "playwright"; // or "patchright"
const API = "https://www.clearcotelabs.com/api/v1/browsers";
const AUTH = { authorization: "Bearer " + process.env.CLEARCOTE_API_KEY };
const RETRY_CODES = new Set(["NO_CAPACITY", "NO_WORKER"]);
export async function createSession(options: Record<string, unknown> = {}, attempts = 5) {
for (let i = 0; ; i++) {
const res = await fetch(API, {
method: "POST",
headers: { ...AUTH, "content-type": "application/json" },
body: JSON.stringify(options),
});
const body = await res.json().catch(() => ({}));
if (res.ok) return body as { id: string; connectUrl: string; worker: string };
const retry = RETRY_CODES.has(body.code) || (res.status === 429 && !body.code) || [500, 502, 504].includes(res.status);
if (!retry || i + 1 >= attempts) throw new Error([res.status, body.code, body.error].filter(Boolean).join(" "));
await new Promise((r) => setTimeout(r, Math.min(15_000, 1000 * 2 ** i) * (0.5 + Math.random())));
}
}
export async function withBrowser<T>(options: Record<string, unknown>, work: (browser: Browser) => Promise<T>) {
const session = await createSession(options);
try {
const browser = await chromium.connectOverCDP(session.connectUrl, { timeout: 120_000 });
try {
return await work(browser);
} finally {
await browser.close().catch(() => {});
}
} finally {
// Ends the session if closing the browser did not (a no-op otherwise).
await fetch(API + "/" + session.id, { method: "DELETE", headers: AUTH }).catch(() => {});
}
}
// await withBrowser({ profile: { name: "shop", persist: true }, country: "de" }, async (browser) => {
// const page = browser.contexts()[0].pages()[0];
// await page.goto("https://example.com");
// });Dateien hochladen
Eine Seite, die nach einer Datei fragt — ein <input type="file">, ein „Durchsuchen“-Button, ein Drag-and-Drop-Bereich — nimmt sie in einem gehosteten Browser genauso entgegen wie in einem lokalen. Die Datei wird auf Ihrem Rechner gelesen, und ihre Bytes laufen über die Verbindung, sodass der Browser nie einen Pfad auf Ihrer Festplatte sieht und Sie eine Datei hochladen können, die nur dort existiert, wo Ihr Skript läuft. Das Limit liegt bei 50 MB pro Datei.
Playwright ist am einfachsten. setInputFiles legt eine Datei direkt in das Input-Feld, ohne Klick, und funktioniert auch, wenn das Input-Feld verborgen ist — viele Sites verbergen das echte Input-Feld hinter einem gestylten Button, zielen Sie also auf das Input-Feld selbst, statt zu klicken.
// Node.js + Playwright
await page.setInputFiles("input[type=file]", "C:/Users/me/invoice.pdf");
// or build the file in your script, with nothing on disk:
await page.setInputFiles("input[type=file]", {
name: "invoice.pdf",
mimeType: "application/pdf",
buffer: Buffer.from("%PDF-1.4 …"),
});# Python + Playwright
page.set_input_files("input[type=file]", "/home/me/invoice.pdf")Öffnet ein Button den System-Dateidialog und gibt es kein Input-Feld, auf das Sie zielen können, fangen Sie stattdessen den Dateidialog ab:
const [chooser] = await Promise.all([
page.waitForEvent("filechooser"),
page.click("text=Browse"), // the page's own button
]);
await chooser.setFiles("C:/Users/me/invoice.pdf");Puppeteer. elementHandle.uploadFile() und fileChooser.accept()stehen in gehosteten Browsern nicht zur Verfügung: Sie benennen einen Pfad, den der Server lesen soll und der irgendwohin auf dem Worker zeigen könnte, weshalb das Gateway sie ablehnt. Bauen Sie die Datei in der Seite selbst aus Bytes, die Sie hineinsenden, und übergeben Sie sie dem Input-Feld:
// Puppeteer: construct the file in the page
const b64 = fs.readFileSync("invoice.pdf").toString("base64");
await page.evaluate(({ b64, name, type }) => {
const data = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
const dt = new DataTransfer();
dt.items.add(new File([data], name, { type }));
const input = document.querySelector("input[type=file]");
input.files = dt.files;
input.dispatchEvent(new Event("change", { bubbles: true }));
}, { b64, name: "invoice.pdf", type: "application/pdf" });Dasselbe DataTransfer-Objekt treibt eine Drag-and-Drop-Zone an: Lösen Sie darauf dragenter, dragover und drop aus, die dieses Objekt tragen. Ein echtes CDP-Drag mit einem lokalen Pfad (Input.dispatchDragEvent mit Dateien) wird aus demselben Grund abgelehnt wie uploadFile().
Dateien herunterladen
Eine Datei, die die Seite herunterlädt, wird auf unserem Server im eigenen Ordner der Session gespeichert. Sie rufen sie über die Verbindung ab, die Ihr Skript bereits hat, mit vier Befehlen der Hosted-Domain, die das gehostete Gateway selbst beantwortet und die Sie über eine beliebige CDP-Session senden. Der Ordner wird gelöscht, wenn die Session endet; rufen Sie also alles Nötige ab, bevor Sie den Browser schließen.
Playwright speichert jeden Download unter einer ID. Hosted.listFiles zeigt diese ID als name der Datei und ergänzt den Namen, den die Site der Datei gegeben hat; vergleichen Sie also mit suggestedFilename():
// Node.js + Playwright
const cdp = await browser.newBrowserCDPSession();
const [download] = await Promise.all([
page.waitForEvent("download"),
page.click("text=Export"), // whatever starts the download
]);
// Wait until the browser has finished writing it.
const isIt = (f) => f.download?.suggestedFilename === download.suggestedFilename() && f.download.state === "completed";
let file;
while (!(file = (await cdp.send("Hosted.listFiles")).files.find(isIt))) {
await new Promise((r) => setTimeout(r, 250));
}
// Read it in chunks (4 MB each unless you pass length, 8 MB at most).
const parts = [];
for (let offset = 0, eof = false; !eof; ) {
const chunk = await cdp.send("Hosted.readFile", { name: file.name, offset });
parts.push(Buffer.from(chunk.data, "base64"));
offset += chunk.bytes;
eof = chunk.eof;
}
fs.writeFileSync(download.suggestedFilename(), Buffer.concat(parts));
await cdp.send("Hosted.deleteFile", { name: file.name }); // frees room in the session's folder# Python + Playwright
import base64, time
cdp = browser.new_browser_cdp_session()
with page.expect_download() as info:
page.click("text=Export")
name = info.value.suggested_filename
def find():
for f in cdp.send("Hosted.listFiles")["files"]:
d = f.get("download") or {}
if d.get("suggestedFilename") == name and d.get("state") == "completed":
return f
file = find()
while not file:
time.sleep(0.25)
file = find()
data, offset = b"", 0
while True:
chunk = cdp.send("Hosted.readFile", {"name": file["name"], "offset": offset})
data += base64.b64decode(chunk["data"])
offset += chunk["bytes"]
if chunk["eof"]:
break
cdp.send("Hosted.deleteFile", {"name": file["name"]})Puppeteer und andere Clients, die die Download-Einstellungen nicht ändern, erhalten die Datei unter dem Namen, den die Site ihr gegeben hat. Sie erscheint, sobald der Download abgeschlossen ist; bis dahin schreibt der Browser eine .crdownload-Datei, die mit partial: true gelistet wird.
// Puppeteer
const cdp = await page.createCDPSession();
await page.click("#export");
let file;
while (!(file = (await cdp.send("Hosted.listFiles")).files.find((f) => f.name === "report.csv"))) {
await new Promise((r) => setTimeout(r, 250));
}
const { data, eof } = await cdp.send("Hosted.readFile", { name: file.name }); // loop on offset for files over 4 MB| Befehl | Nimmt | Liefert |
|---|---|---|
Hosted.listFiles | nichts | files: name, size, modified (ms), partial und download (suggestedFilename, url, state) für einen Download, den Playwright benannt hat; dazu totalBytes und limits. |
Hosted.readFile | name, offset (0), length (4 MB, höchstens 8 MB) | data (base64), offset, bytes, size, eof |
Hosted.deleteFile | name | nichts |
Hosted.writeFile | name, data (base64, höchstens 8 MB pro Aufruf), append | name, size |
Ein name ist immer genau ein Dateiname, so wie listFiles ihn liefert, nie ein Pfad. Der Ordner fasst höchstens 1 GB, Downloads und von Ihnen hineingelegte Dateien zusammen. Lädt ein Browser darüber hinaus herunter, endet die Session (Grund max_files_size); löschen Sie in einer langen Session also, was Sie abgerufen haben.
Hosted.writeFile legt eine Datei in den Ordner der Session, um sie später in derselben Session wieder zu lesen: bis zu 50 MB pro Datei, gesendet in Aufrufen von höchstens 8 MB, den Rest mit append: true. Ausführbare Dateitypen (.exe, .bat, .ps1 und ähnliche) werden abgelehnt. Eine Seite kann keine Dateien aus diesem Ordner öffnen; um einer Seite eine Datei zu geben, verwenden Sie setInputFiles wie unter Dateien hochladen.
Der Playground
Der Playground im Dashboard startet einen dieser Browser, und Sie sehen ihm in der Live-Ansicht zu. Er öffnet sich auf Task: Sie schreiben, was der Browser tun soll, und ein Agent erledigt es Schritt für Schritt. Das ist ein Agent-Run, derselbe wie mit POST /api/v1/runs, und jeder Schritt erscheint unter What it did, sobald er passiert. Sie können in der Live-Ansicht jederzeit die Kontrolle übernehmen. Ist Ask me when it gets stuck eingeschaltet (das ist der Standard), hält der Agent an, wenn er eine Person braucht, etwa für einen Anmeldecode, und macht weiter, sobald Sie das als erledigt markieren.
Die Chips unter der Aufgabe legen fest, wo sie beginnt (Start at), aus welchem Land die Residential-IP kommt (Exit), ob es ein frisches Gerät ist oder eines, das wiederkommt (Device), und ob die Antwort Text ist oder JSON in einer von Ihnen vorgegebenen Form (Output). Unter More liegen alle übrigen Session-Optionen, die Höchstzahl der Schritte, eine Videoaufzeichnung und Secrets: Schreiben Sie {{password}} in die Aufgabe und tragen Sie dort den Wert ein. Das Modell sieht nur den Platzhalter, und der Wert bleibt in Ihrem Tab: Er wird nie gespeichert und ist nie Teil eines Links.
Script führt stattdessen Ihren eigenen Code aus. Er läuft in einem Sandbox-Frame in Ihrem Tab und spricht über den WebSocket des Browsers direkt CDP mit ihm. log() schreibt unter What it did, und unter More können Sie den Browser offen lassen, damit das nächste Skript darin weiterläuft. Sein page ist ein kleiner Helper, nicht Playwright – ein Playground-Skript ist also eine Skizze, die Sie übertragen müssen, keine Datei zum Einfügen:
| Helper | Wirkung |
|---|---|
page.goto(url, { timeout? }) | Navigieren und auf das load-Event warten. |
page.click(sel) · page.type(sel, text) · page.press(key) | Echte Maus- und Tastatureingaben; das Element wird vorher in den sichtbaren Bereich gescrollt. |
page.evaluate(fn, ...args) | Eine Funktion in der Seite ausführen und ihr JSON-Ergebnis zurückbekommen. |
page.waitForSelector(sel, { timeout? }) · page.waitForNavigation() | Auf ein Element warten oder darauf, dass die nächste Seite geladen ist. |
page.scroll(px) · page.screenshot({ fullPage? }) | Mit dem Mausrad scrollen; ein JPEG, das im Ergebnis des Laufs erscheint. |
page.title() · page.url() · page.content() | Titel, Adresse und HTML des Dokuments. |
log(...values) · sleep(ms) | Eine Zeile unter What it did ausgeben (Objekte werden formatiert ausgegeben); pausieren. |
cdp(method, params) | Ein roher CDP-Befehl an den Browser (Target.*, Browser.*, Storage.*). |
page.cdp(method, params) | Ein roher CDP-Befehl an die Seite (Page.*, Runtime.*, DOM.*, Network.*). |
Fehler nennen die Skriptzeile, aus der sie stammen. Save as… speichert ein Skript in diesem Browser.
Wenn ein Lauf endet, erscheint darunter sein Ergebnis: bei einer Aufgabe die Antwort und die Seite, auf der sie endete, dazu die Aufzeichnung, falls Sie eine angefordert haben, und die vollständige Zeitleiste des Laufs; bei einem Skript seine Screenshots. Das Ergebnis bietet denselben Lauf auf drei weitere Arten an. Use in code zeigt ihn als Code für Ihr eigenes Projekt: eine Aufgabe als Aufruf der Runs-API in Node, Python oder curl, ein Skript als denselben Browser mit denselben Optionen für Playwright oder Puppeteer. Copy for AI kopiert einen Prompt für einen Coding-Agenten mit der API, diesem Lauf und seinen Optionen. Share kopiert einen Link, der die Aufgabe oder das Skript samt Optionen in der URL trägt, bei uns wird also nichts gespeichert; wer den Link öffnet, führt ihn auf eigenes Guthaben aus. Keiner der drei enthält den Wert eines Secrets.