Saltar al contenido
Browsa
  1. Guías
  2. Playwright y Puppeteer

Conecta Playwright o Puppeteer a un navegador en la nube por CDP.

Un navegador en la nube por CDP es un navegador real que se ejecuta en el servidor de otro y habla el Chrome DevTools Protocol, así que tu propio código de Playwright o Puppeteer lo controla igual que a un navegador local. En Browsa, una llamada a la API inicia el navegador y devuelve su dirección CDP; cambias la línea que lanza el navegador y conservas el resto del script.

Tiempo
Unos 5 minutos
Precio
1 crédito por cada bloque de 12 minutos iniciado de navegador, 5 por una hora completa
Funciona con
Playwright (Python, Node), Puppeteer, cualquier cliente CDP

¿Cómo ejecuto Playwright en la nube?

  1. Inicia un navegador. POST /v1/agents (o create_agent() en el SDK) inicia un navegador Phantom en la nube de Browsa y devuelve su id, su dirección cdp_http y un live_url que puedes abrir para verlo.
  2. Conéctate. Sustituye chromium.launch() por chromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY}), o puppeteer.launch() por puppeteer.connect({ browserURL, headers }). El navegador ya tiene un contexto y una página abierta: úsalos.
  3. 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

Terminal
pip install browsa playwright

No necesitas playwright install: el navegador se ejecuta en Browsa.

cloud_playwright.py
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

Terminal
npm i browsa playwright
cloud-playwright.ts
import { 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.

Terminal
npm i browsa puppeteer-core
cloud-puppeteer.ts
import { 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
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:

Python
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
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 ejecutasCréditos
Navegador que funciona hasta 12 minutos1
Navegador que funciona una hora completa5
Identidad persistente, cada 30 días50
Sesión en una identidad persistente (hasta 1 hora)1
Navegador que no llega a iniciarseReembolsado

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.

Próximos pasos

Ejecuta tu script en un navegador en la nube.

100 créditos gratis. Sin tarjeta, sin suscripción.