Como rodar Playwright na nuvem?
- Inicie um navegador.
POST /v1/agents(oucreate_agent()no SDK) inicia um navegador Phantom na nuvem da Browsa e retorna oid, o endereçocdp_httpe umalive_urlque você pode abrir para acompanhar. - Conecte. Troque
chromium.launch()porchromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY}), oupuppeteer.launch()porpuppeteer.connect({ browserURL, headers }). O navegador já tem um contexto e uma página aberta: use-os. - Encerre. Chame
destroy_agent()quando terminar, ou deixe o navegador desligar quando o TTL acabar. Você paga 1 crédito a cada 12 minutos iniciados de execução; o restante do que ele reservou volta para você.
Você precisa de uma chave de API da Browsa (ela começa com agt_live_). Crie sua conta e ganhe 100 créditos grátis assim que confirmar seu e-mail, sem cartão. Não é preciso instalar o Chrome na sua máquina nem na sua imagem Docker.
Conecte seu cliente
Playwright em Python
pip install browsa playwrightVocê não precisa de playwright install: o navegador roda na 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 em TypeScript ou 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
Use puppeteer-core. Ele tem a mesma API do puppeteer, mas não baixa um navegador, que você não precisa mais.
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 puro e outros clientes
A resposta de criação traz dois endereços. cdp_http é o endpoint HTTP do navegador, o que o Playwright e o Puppeteer esperam. cdp_url é o WebSocket de uma única página, para clientes que falam CDP diretamente. Os dois exigem sua chave no header X-API-Key. Qualquer biblioteca que consiga se conectar a um navegador existente via CDP com um header personalizado pode usar o mesmo endereço; é assim que funcionam os guias de browser-use e Stagehand.
Sem o SDK, inicie o navegador com HTTP puro:
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 é o que o navegador reserva enquanto roda: 1 crédito para um TTL de até 5 minutos, 5 para um maior. Quando ele termina, os blocos de 12 minutos não usados voltam para o seu saldo.
O que muda em relação a um navegador local?
Viewport e user agent
Tamanho da tela, user agent, fuso horário, idioma, geolocalização e número de CPUs são definidos juntos quando o navegador inicia. Comandos de emulação do CDP que mudam só um deles retornam sucesso e não mudam nada, então page.set_viewport_size(), page.setViewport() e page.setUserAgent() não têm efeito.
O que fazerPasse screen_resolution e os_type para POST /v1/agents. Para controlar a emulação você mesmo, adicione cdp_overrides=allow à query do endereço CDP; manter o fingerprint consistente passa a ser responsabilidade sua.
Contextos e páginas
O navegador inicia com um contexto e uma página aberta.
O que fazerUse browser.contexts[0] e a primeira página dele em vez de criar um novo contexto.
Downloads de arquivos
Os arquivos baixados ficam no navegador na nuvem, e o evento de download do Playwright informa canceled.
O que fazerBusque o arquivo de dentro da página (veja abaixo), o que usa os cookies e o endereço IP do navegador.
Tempo de vida
Um navegador roda até o TTL acabar, no máximo 1 hora, ou até você destruí-lo. Ele não encerra por inatividade.
O que fazerPeça o TTL de que precisa ("5m" a "1h"). Inicie um novo navegador para jobs mais longos, ou use uma identidade salva para manter os logins entre eles.
Rede
Sem proxy, o tráfego sai do data center da Browsa com um endereço IP de data center.
O que fazerPasse uma rede da Browsa em proxy ({"network": "residential"}), seu próprio proxy HTTP, HTTPS ou SOCKS5, ou um proxy salvo em proxy_id.
Sinais de automação
Playwright e Puppeteer ativam o domínio Runtime do CDP ao se conectar, e algumas verificações anti-bot conseguem detectar isso.
O que fazerSe um site sinalizar seu cliente, tente um cliente CDP puro sem Runtime.enable, ou o próprio agente de tarefas da Browsa (POST /v1/tasks). Veja os resultados com data na página de benchmarks.
Navegadores em paralelo
6 vagas de navegador por workspace. Uma requisição com todas as vagas ocupadas retorna 429 com Retry-After: 30 e não é cobrada.
O que fazerEnfileire o trabalho do seu lado, ou envie um e-mail para support@browsa.io pedindo mais vagas.
Como reconectar depois que a conexão cai?
Fechar a conexão do Playwright ou do Puppeteer não para o navegador. Ele continua rodando até o TTL acabar, então outro processo pode se conectar a ele. Pegue o endereço de novo com GET /v1/agents/{id}/cdp (ou get_agent(agent_id) em Python, getAgent(agentId) em TypeScript) e conecte com o mesmo header X-API-Key. O endpoint retorna 409 quando o navegador não está mais rodando.
Como baixar um arquivo?
Busque o arquivo de dentro da página e retorne os bytes:
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))Como usar meu próprio proxy?
Adicione um objeto proxy ao iniciar o navegador. O navegador passa a usar o endereço IP do proxy e, com country definido, o fuso horário e o idioma acompanham esse país. O tráfego via proxy não tem custo extra na 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"
}'Um navegador puro inicia mesmo se o proxy estiver inacessível, então teste o proxy antes. Um proxy salvo tem um endpoint de verificação e pode ser passado como proxy_id.
Como manter os logins entre execuções?
Use uma identidade persistente em vez de um navegador descartável. Ela mantém cookies, local storage e fingerprint entre sessões. Crie uma vez com "mode": "persistent" e abra uma sessão sempre que um script precisar: POST /v1/agents/{id}/sessions retorna o mesmo formato de um navegador novo, incluindo cdp_http, e você se conecta exatamente como acima. Uma identidade custa 50 créditos a cada 30 dias e cada sessão custa 1 crédito. Veja Abrir uma sessão.
Quanto custa?
| O que você roda | Créditos |
|---|---|
| Navegador que roda até 12 minutos | 1 |
| Navegador que roda uma hora inteira | 5 |
| Identidade persistente, a cada 30 dias | 50 |
| Sessão em uma identidade persistente (até 1 hora) | 1 |
| Navegador que não consegue iniciar | Reembolsado |
Um crédito custa $0.10 no pacote Starter de $20, e menos nos pacotes maiores. Os créditos não expiram. Preços completos.
Solução de problemas
401 Unauthorized ao conectar
O header X-API-Key não chegou à Browsa, ou a chave está errada. Envie o header na chamada de conexão exatamente como nos exemplos e confira se a chave começa com agt_.
402 ao iniciar um navegador
INSUFFICIENT_CREDIT significa que o saldo não cobre o TTL pedido; BUDGET_REACHED significa que seu limite mensal de gastos foi atingido. Consulte GET /v1/credits e GET /v1/budget.
A conexão cai depois de alguns minutos
O navegador chegou ao fim do TTL. Peça um TTL maior, de até "1h".
Perguntas
Por que set_viewport_size() não muda o navegador?
Tamanho da tela, user agent, fuso horário, idioma e geolocalização de um navegador da Browsa são definidos juntos quando ele é criado, para que a página encontre uma máquina consistente. Comandos de emulação do CDP que mudariam só um deles retornam sucesso e não mudam nada. Defina screen_resolution e os_type ao criar o navegador, ou adicione cdp_overrides=allow ao endereço CDP se quiser controlar a emulação você mesmo.
Como baixar um arquivo de um navegador na nuvem?
Os arquivos que uma página baixa ficam no navegador na nuvem, e o Playwright informa o download como cancelado. Busque o arquivo de dentro da página com page.evaluate(), que usa os cookies e o endereço IP do navegador, e retorne os bytes em base64.
Quantos navegadores podem rodar ao mesmo tempo?
Um workspace tem 6 vagas de navegador. Cada navegador em execução ocupa uma, assim como cada identidade salva. Um novo navegador com todas as vagas ocupadas retorna 429 TOO_MANY_REQUESTS com Retry-After: 30, e nada é cobrado. Envie um e-mail para support@browsa.io se precisar de mais.
A Browsa fornece proxies?
Sim. Data center a 5 créditos por GB, residencial a 50 créditos por GB. Ou passe seu próprio proxy HTTP, HTTPS ou SOCKS5 por navegador, grátis. Sem proxy, o navegador usa o endereço IP do data center da Browsa.