¿Cómo ejecuto Playwright en la nube?
- Inicia un navegador.
POST /v1/agents(ocreate_agent()en el SDK) inicia un navegador Phantom en la nube de Browsa y devuelve suid, su direccióncdp_httpy unlive_urlque puedes abrir para verlo. - Conéctate. Sustituye
chromium.launch()porchromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY}), opuppeteer.launch()porpuppeteer.connect({ browserURL, headers }). El navegador ya tiene un contexto y una página abierta: úsalos. - Limpia. Llama a
destroy_agent()cuando termines, o deja que el navegador se apague al acabar su TTL. Pagas 1 crédito por cada bloque de 12 minutos iniciado que funcionó; el resto de lo que reservó vuelve a tu saldo.
Necesitas una clave de API de Browsa (empieza por agt_live_). Regístrate y recibe 100 créditos gratis al verificar tu correo, sin tarjeta. No hay que instalar Chrome en tu equipo ni en tu imagen de Docker.
Conecta tu cliente
Playwright en Python
pip install browsa playwrightNo necesitas playwright install: el navegador se ejecuta en 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 en TypeScript o 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
Usa puppeteer-core. Tiene la misma API que puppeteer, pero no descarga ningún navegador, que ya no necesitas.
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 directo y otros clientes
La respuesta de creación trae dos direcciones. cdp_http es el endpoint HTTP del navegador, el que esperan Playwright y Puppeteer. cdp_url es el WebSocket de una sola página, para clientes que hablan CDP directamente. Ambas necesitan tu clave en un encabezado X-API-Key. Cualquier librería que pueda conectarse a un navegador existente por CDP con un encabezado personalizado puede usar la misma dirección; así funcionan las guías de browser-use y Stagehand.
Sin el SDK, inicia el navegador con HTTP simple:
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 es lo que el navegador retiene mientras funciona: 1 crédito para un TTL de hasta 5 minutos, 5 para uno más largo. Cuando termina, los bloques de 12 minutos que no usó vuelven a tu saldo.
¿Qué cambia respecto a un navegador local?
Viewport y user agent
El tamaño de pantalla, el user agent, la zona horaria, el idioma, la geolocalización y el número de CPU se definen juntos al iniciar el navegador. Los comandos de emulación de CDP que cambian solo uno de ellos devuelven éxito y no cambian nada, así que page.set_viewport_size(), page.setViewport() y page.setUserAgent() no tienen efecto.
Qué hacerPasa screen_resolution y os_type a POST /v1/agents. Para controlar tú la emulación, añade cdp_overrides=allow como parámetro de consulta de la dirección CDP; mantener la huella digital coherente pasa a ser cosa tuya.
Contextos y páginas
El navegador arranca con un contexto y una página abierta.
Qué hacerUsa browser.contexts[0] y su primera página en lugar de crear un contexto nuevo.
Descargas de archivos
Los archivos descargados se quedan en el navegador en la nube, y el evento de descarga de Playwright informa canceled.
Qué hacerObtén el archivo desde dentro de la página (ver más abajo), que usa las cookies y la dirección IP del navegador.
Duración
Un navegador funciona hasta que acaba su TTL, como máximo 1 hora, o hasta que lo destruyes. No se cierra por inactividad.
Qué hacerPide el TTL que necesites (de "5m" a "1h"). Inicia un navegador nuevo para trabajos más largos, o usa una identidad guardada para conservar los logins entre ellos.
Red
Sin proxy, el tráfico sale del centro de datos de Browsa con una dirección IP de centro de datos.
Qué hacerPasa una red de Browsa en proxy ({"network": "residential"}), tu propio proxy HTTP, HTTPS o SOCKS5, o uno guardado en proxy_id.
Señales de automatización
Playwright y Puppeteer activan el dominio Runtime de CDP al conectarse, y algunas detecciones de bots lo notan.
Qué hacerSi un sitio marca tu cliente, prueba un cliente CDP directo sin Runtime.enable, o el propio agente de tareas de Browsa (POST /v1/tasks). Consulta los resultados con fecha en la página de benchmarks.
Navegadores en paralelo
6 slots de navegador por espacio de trabajo. Una solicitud con todos los slots ocupados devuelve 429 con Retry-After: 30 y no se cobra.
Qué hacerPon el trabajo en cola de tu lado, o escribe a support@browsa.io para pedir más slots.
¿Cómo me reconecto si se corta la conexión?
Cerrar tu conexión de Playwright o Puppeteer no detiene el navegador. Sigue funcionando hasta que acaba su TTL, así que otro proceso puede conectarse a él. Vuelve a obtener su dirección con GET /v1/agents/{id}/cdp (o get_agent(agent_id) en Python, getAgent(agentId) en TypeScript) y conéctate con el mismo encabezado X-API-Key. El endpoint devuelve 409 cuando el navegador ya no está en marcha.
¿Cómo descargo un archivo?
Obtenlo desde dentro de la página y devuelve los 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))¿Cómo uso mi propio proxy?
Añade un objeto proxy al iniciar el navegador. El navegador usa entonces la dirección IP del proxy y, con country definido, su zona horaria e idioma siguen a ese país. El tráfico por proxy no cuesta nada extra en 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"
}'Un navegador simple arranca aunque el proxy no responda, así que compruébalo antes. Un proxy guardado tiene un endpoint de comprobación y puede pasarse como proxy_id.
¿Cómo conservo los logins entre ejecuciones?
Usa una identidad persistente en lugar de un navegador desechable. Conserva sus cookies, el almacenamiento local y la huella digital entre sesiones. Créala una vez con "mode": "persistent" y abre una sesión cuando un script la necesite: POST /v1/agents/{id}/sessions devuelve la misma forma que un navegador nuevo, incluido cdp_http, y te conectas exactamente como arriba. Una identidad cuesta 50 créditos cada 30 días y cada sesión cuesta 1 crédito. Consulta Abrir una sesión.
¿Cuánto cuesta?
| Lo que ejecutas | Créditos |
|---|---|
| Navegador que funciona hasta 12 minutos | 1 |
| Navegador que funciona una hora completa | 5 |
| Identidad persistente, cada 30 días | 50 |
| Sesión en una identidad persistente (hasta 1 hora) | 1 |
| Navegador que no llega a iniciarse | Reembolsado |
Un crédito cuesta $0.10 con el paquete Starter de $20, y menos con paquetes más grandes. Los créditos nunca expiran. Todos los precios.
Solución de problemas
401 Unauthorized al conectar
El encabezado X-API-Key no llegó a Browsa, o la clave es incorrecta. Envíalo en la llamada de conexión exactamente como en los ejemplos, y comprueba que la clave empiece por agt_.
402 al iniciar un navegador
INSUFFICIENT_CREDIT significa que el saldo no cubre el TTL que pediste; BUDGET_REACHED significa que alcanzaste tu límite de gasto mensual. Revisa GET /v1/credits y GET /v1/budget.
La conexión se corta a los pocos minutos
El navegador llegó al final de su TTL. Pide uno más largo, de hasta "1h".
Preguntas
¿Por qué set_viewport_size() no cambia el navegador?
El tamaño de pantalla, el user agent, la zona horaria, el idioma y la geolocalización de un navegador de Browsa se definen juntos al crearlo, para que la página vea una máquina coherente. Los comandos de emulación de CDP que cambiarían solo uno de ellos devuelven éxito y no cambian nada. Define screen_resolution y os_type al crear el navegador, o añade cdp_overrides=allow a la dirección CDP si quieres controlar tú la emulación.
¿Cómo descargo un archivo desde un navegador en la nube?
Los archivos que descarga una página se quedan en el navegador en la nube, y Playwright marca la descarga como cancelada. Obtén el archivo desde dentro de la página con page.evaluate(), que usa las cookies y la dirección IP del navegador, y devuelve los bytes en base64.
¿Cuántos navegadores pueden funcionar a la vez?
Un espacio de trabajo tiene 6 slots de navegador. Cada navegador en marcha ocupa uno, y también cada identidad guardada. Un navegador nuevo con todos los slots ocupados devuelve 429 TOO_MANY_REQUESTS con Retry-After: 30, y no se cobra nada. Escribe a support@browsa.io si necesitas más.
¿Browsa ofrece proxies?
Sí. Centro de datos a 5 créditos por GB, residencial a 50 créditos por GB. O pasa tu propio proxy HTTP, HTTPS o SOCKS5 por navegador, gratis. Sin proxy, el navegador usa la dirección IP del centro de datos de Browsa.