Как запустить Playwright в облаке?
- Запустите браузер.
POST /v1/agents(илиcreate_agent()в SDK) запускает браузер Phantom в облаке Browsa и возвращает егоid, адресcdp_httpиlive_url, по которому можно смотреть браузер. - Подключитесь. Замените
chromium.launch()наchromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY})илиpuppeteer.launch()наpuppeteer.connect({ browserURL, headers }). У браузера уже есть контекст и открытая страница: используйте их. - Освободите ресурсы. Вызовите
destroy_agent(), когда закончите, или дайте браузеру завершиться по истечении TTL. Списывается 1 кредит за каждые начатые 12 минут работы, остальной резерв возвращается.
Нужен API-ключ Browsa (начинается с agt_live_). Зарегистрируйтесь и получите 100 бесплатных кредитов после подтверждения email, без карты. Устанавливать Chrome на машину или в Docker-образ не нужно.
Подключите клиент
Playwright на Python
pip install browsa playwrightplaywright install не нужен: браузер работает в Browsa.
import os
from browsa import Client
from playwright.sync_api import sync_playwright
API_KEY = os.environ["BROWSA_API_KEY"]
client = Client(api_key=API_KEY)
agent = client.create_agent(ttl="10m") # a cloud browser, up to 10 minutes
try:
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(
agent["cdp_http"], headers={"X-API-Key": API_KEY}
)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://example.com")
print(page.title())
# the rest is plain Playwright
finally:
client.destroy_agent(agent["id"])Playwright на TypeScript или Node
npm i browsa playwrightimport { Client } from "browsa";
import { chromium } from "playwright";
const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "10m" });
try {
const browser = await chromium.connectOverCDP(agent.cdp_http, {
headers: { "X-API-Key": apiKey },
});
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
console.log(await page.title());
} finally {
await client.destroyAgent(agent.id);
}Puppeteer
Используйте puppeteer-core. У него тот же API, что у puppeteer, но он не скачивает браузер, который вам больше не нужен.
npm i browsa puppeteer-coreimport { Client } from "browsa";
import puppeteer from "puppeteer-core";
const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "5m" });
try {
const browser = await puppeteer.connect({
browserURL: agent.cdp_http,
headers: { "X-API-Key": apiKey },
});
const [page] = await browser.pages();
await page.goto("https://example.com");
console.log(await page.title());
await browser.disconnect();
} finally {
await client.destroyAgent(agent.id);
}Чистый CDP и другие клиенты
Ответ на создание содержит два адреса. cdp_http: HTTP-эндпоинт браузера, его ждут Playwright и Puppeteer. cdp_url: WebSocket одной страницы, для клиентов, которые работают с CDP напрямую. Обоим нужен ваш ключ в заголовке X-API-Key. Тот же адрес подойдёт любой библиотеке, которая умеет подключаться к запущенному браузеру по CDP с собственным заголовком; так работают руководства по browser-use и Stagehand.
Без SDK запустите браузер обычным HTTP-запросом:
curl https://browsa.io/v1/agents \
-H "X-API-Key: $BROWSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttl": "10m", "initial_url": "https://example.com"}'
# -> { "id": "agt_…", "status": "running", "cdp_http": "https://browsa.io/api/v1/cdp/…",
# "cdp_url": "wss://browsa.io/api/v1/cdp/…/ws/page/…", "live_url": "…", "cost_credits": 5 }cost_credits показывает, сколько браузер резервирует, пока работает: 1 кредит для TTL до 5 минут, 5 для более долгого. Когда он завершается, неиспользованные блоки по 12 минут возвращаются на баланс.
Что работает иначе, чем в локальном браузере?
Размер окна и user agent
Размер экрана, user agent, часовой пояс, язык, геолокация и число ядер CPU задаются вместе при запуске браузера. Команды эмуляции CDP, которые меняют что-то одно, возвращают успех и ничего не меняют, поэтому page.set_viewport_size(), page.setViewport() и page.setUserAgent() не действуют.
Что делатьПередайте screen_resolution и os_type в POST /v1/agents. Чтобы управлять эмуляцией самим, добавьте cdp_overrides=allow в query CDP-адреса; за согласованность отпечатка тогда отвечаете вы.
Контексты и страницы
Браузер запускается с контекстом и открытой страницей.
Что делатьИспользуйте browser.contexts[0] и его первую страницу, а не создавайте новый контекст.
Загрузка файлов
Скачанные файлы остаются в облачном браузере, а событие download в Playwright сообщает canceled.
Что делатьПолучите файл внутри страницы (см. ниже), с cookies и IP-адресом браузера.
Время жизни
Браузер работает до конца TTL, максимум 1 час, или пока вы его не удалите. Из-за простоя он не завершается.
Что делатьЗапрашивайте нужный TTL (от "5m" до "1h"). Для долгих задач запускайте новый браузер или используйте сохранённый профиль, чтобы логины сохранялись между ними.
Сеть
Без прокси трафик выходит из дата-центра Browsa с IP-адресом дата-центра.
Что делатьПередайте сеть Browsa в proxy ({"network": "residential"}), свой HTTP-, HTTPS- или SOCKS5-прокси или сохранённый прокси в proxy_id.
Признаки автоматизации
Playwright и Puppeteer при подключении включают домен Runtime в CDP, и некоторые проверки на ботов это видят.
Что делатьЕсли сайт помечает ваш клиент, попробуйте чистый CDP-клиент без Runtime.enable или собственного агента Browsa (POST /v1/tasks). Результаты с датами есть на странице бенчмарков.
Параллельные браузеры
6 слотов для браузеров на рабочее пространство. Запрос при занятых слотах возвращает 429 с Retry-After: 30 и не оплачивается.
Что делатьСтавьте задачи в очередь на своей стороне или напишите на support@browsa.io, чтобы получить больше слотов.
Как переподключиться после обрыва?
Закрытие соединения Playwright или Puppeteer не останавливает браузер. Он работает до конца TTL, так что к нему может подключиться другой процесс. Получите его адрес снова через GET /v1/agents/{id}/cdp (или get_agent(agent_id) в Python, getAgent(agentId) в TypeScript) и подключитесь с тем же заголовком X-API-Key. Если браузер уже не работает, эндпоинт возвращает 409.
Как скачать файл?
Получите его изнутри страницы и верните байты:
import base64
b64 = page.evaluate("""async (url) => {
const buf = new Uint8Array(await (await fetch(url)).arrayBuffer());
let s = ""; for (const b of buf) s += String.fromCharCode(b);
return btoa(s);
}""", "https://example.com/report.pdf")
open("report.pdf", "wb").write(base64.b64decode(b64))Как использовать свой прокси?
Добавьте объект proxy при запуске браузера. Браузер будет использовать IP-адрес прокси, а если задан country, его часовой пояс и язык подстроятся под эту страну. Трафик через прокси в Browsa ничего дополнительно не стоит.
curl https://browsa.io/v1/agents \
-H "X-API-Key: $BROWSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ttl": "10m",
"proxy": {"type": "http", "host": "proxy.example.com", "port": 8080,
"username": "your-proxy-user", "password": "your-proxy-password"},
"country": "de"
}'Браузер запускается, даже если прокси недоступен, поэтому сначала проверьте его. У сохранённого прокси есть эндпоинт проверки, и его можно передать как proxy_id.
Как сохранять логины между запусками?
Используйте постоянный профиль вместо одноразового браузера. Он хранит cookies, local storage и отпечаток между сессиями. Создайте его один раз с "mode": "persistent", а затем открывайте сессию, когда она нужна скрипту: POST /v1/agents/{id}/sessions возвращает то же, что и новый браузер, включая cdp_http, и подключение работает точно так же. Профиль стоит 50 кредитов каждые 30 дней, а каждая сессия 1 кредит. См. Открытие сессии.
Сколько это стоит?
| Что вы запускаете | Кредиты |
|---|---|
| Браузер, работающий до 12 минут | 1 |
| Браузер, работающий целый час | 5 |
| Постоянный профиль, каждые 30 дней | 50 |
| Сессия на постоянном профиле (до 1 часа) | 1 |
| Браузер, который не запустился | Возврат |
Один кредит стоит $0.10 в пакете Starter за $20 и дешевле в больших пакетах. Кредиты не сгорают. Все цены.
Решение проблем
401 Unauthorized при подключении
Заголовок X-API-Key не дошёл до Browsa, или ключ неверный. Передавайте его при подключении точно как в примерах и проверьте, что ключ начинается с agt_.
402 при запуске браузера
INSUFFICIENT_CREDIT значит, что баланса не хватает на запрошенный TTL; BUDGET_REACHED значит, что достигнут месячный лимит расходов. Проверьте GET /v1/credits и GET /v1/budget.
Соединение обрывается через несколько минут
Браузер дошёл до конца TTL. Запросите более долгий, до "1h".
Вопросы
Почему set_viewport_size() не меняет браузер?
Размер экрана, user agent, часовой пояс, язык и геолокация браузера Browsa задаются вместе при его создании, чтобы страница видела одну согласованную машину. Команды эмуляции CDP, которые меняют что-то одно, возвращают успех и ничего не меняют. Задайте screen_resolution и os_type при создании браузера или добавьте cdp_overrides=allow к CDP-адресу, если хотите управлять эмуляцией сами.
Как скачать файл из облачного браузера?
Файлы, которые скачивает страница, остаются в облачном браузере, а Playwright сообщает, что загрузка отменена. Получите файл изнутри страницы через page.evaluate(), с cookies и IP-адресом браузера, и верните байты в base64.
Сколько браузеров может работать одновременно?
У рабочего пространства 6 слотов для браузеров. Каждый работающий браузер занимает один, как и каждый сохранённый профиль. Новый браузер при занятых слотах возвращает 429 TOO_MANY_REQUESTS с Retry-After: 30, и ничего не списывается. Если нужно больше, напишите на support@browsa.io.
Browsa предоставляет прокси?
Да. Прокси дата-центра стоят 5 кредитов за ГБ, резидентные 50 кредитов за ГБ. Или передайте свой HTTP-, HTTPS- или SOCKS5-прокси для каждого браузера, бесплатно. Без прокси браузер использует IP-адрес дата-центра Browsa.