Esta guía crea una clave de navegador, arranca un navegador, lo maneja desde tu código y lo para. Son unos cinco minutos.
Antes de empezar
- Acceso. OpenWAF Browsers tiene que estar activado para tu organización. Mientras no lo esté, las escrituras responden
403 feature_disabled. Mira pedir acceso. - Un
adminde toda la organización para crear claves. Para ver el uso y las sesiones bastareadonly. - Node.js 18 o posterior para los ejemplos de Playwright, Puppeteer y MCP.
1. Crea una clave
Una clave de navegador (bdk_…) autentica a tu agente en https://browsers.openwaf.dev. Una organización tiene hasta 5 claves. Cada clave corre hasta 2 navegadores a la vez. El secreto se enseña una sola vez; después el panel y la API solo muestran su prefijo (bdk_ y 4 caracteres).
- Abre Navegadores en el menú de la organización y después la pestaña Claves.
- Elige Crear clave y ponle un nombre, por ejemplo
ci-agent(minúsculas, dígitos y guiones). - Copia el secreto ahora. No lo volverás a ver.
openwaf-cloud ctl browsers keys create ci-agent --reason "Navegador del agente de CI"La CLI enseña lo que va a crear y pregunta antes de aplicarlo; después imprime el secreto una sola vez. Añade --yes para no preguntar (obligatorio sin terminal) o --dry-run para solo verlo. Mira empezar con la CLI para la dirección de la API y el token.
curl -sS -X POST "https://dash.openwaf.dev/v1/orgs/$ORG/browsers/keys" \
-H "Authorization: Bearer $OPENWAF_TOKEN" -H "Content-Type: application/json" \
-H "X-Change-Reason: Navegador del agente de CI" \
-d '{"name": "ci-agent"}'La respuesta 201 trae la clave y su secreto, con Cache-Control: no-store:
{"key": {"id": "6f1c…", "name": "ci-agent", "prefix": "bdk_AbC1", "disabled": false,
"created_at": "2026-10-29T10:00:00Z", "created_by": "…", "rotated_at": null},
"secret": "bdk_…"}Pide a tu asistente, conectado al servidor MCP de OpenWAF con una credencial admin, que cree una clave de navegador. Llama a browser_keys_create con name y un reason: primero con confirm=false para comprobar y después con confirm=true. La respuesta trae el secreto una vez, así que pasa por la conversación: rota la clave más tarde si eso te importa.
Guarda el secreto donde tu agente lee sus secretos. Los ejemplos de abajo lo leen de OPENWAF_BROWSERS_KEY:
read -rs OPENWAF_BROWSERS_KEY && export OPENWAF_BROWSERS_KEY # pega bdk_…2. Arranca un navegador
curl -sS -X POST https://browsers.openwaf.dev/v1/browsers \
-H "X-API-Key: $OPENWAF_BROWSERS_KEY" -H "Content-Type: application/json" \
-d '{"metadata": {"task": "quickstart"}}'Todos los campos del cuerpo son opcionales. La respuesta:
{"id": "bs_…", "status": "running",
"cdpUrl": "wss://browsers.openwaf.dev/cdp/…", "cdpHttpUrl": "https://browsers.openwaf.dev/…",
"liveUrl": "https://browsers.openwaf.dev/…", "urlsExpireAt": "2026-10-29T11:00:00Z", …}Abre liveUrl en tu navegador para mirar. cdpUrl y liveUrl llevan un token válido 1 hora; GET /v1/browsers/{id} devuelve otros nuevos.
Si todos los huecos de la beta están ocupados recibes 429 con {"code": "capacity_busy"} y Retry-After: 30. Si esta clave ya tiene 2 navegadores en marcha recibes 429 con {"code": "key_concurrency"}. Mira errores.
3. Manéjalo
import { chromium } from "playwright";
const api = "https://browsers.openwaf.dev/v1/browsers";
const headers = { "X-API-Key": process.env.OPENWAF_BROWSERS_KEY, "Content-Type": "application/json" };
const b = await (await fetch(api, { method: "POST", headers, body: "{}" })).json();
const browser = await chromium.connectOverCDP(b.cdpUrl);
const page = await browser.contexts()[0].newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.close(); // desconecta; el navegador sigue en marcha hasta que se para o queda inactivo
await fetch(`${api}/${b.id}`, { method: "PATCH", headers, body: JSON.stringify({ action: "stop" }) });import puppeteer from "puppeteer-core";
const api = "https://browsers.openwaf.dev/v1/browsers";
const headers = { "X-API-Key": process.env.OPENWAF_BROWSERS_KEY, "Content-Type": "application/json" };
const b = await (await fetch(api, { method: "POST", headers, body: "{}" })).json();
const browser = await puppeteer.connect({ browserWSEndpoint: b.cdpUrl });
const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());
await browser.disconnect();
await fetch(`${api}/${b.id}`, { method: "PATCH", headers, body: JSON.stringify({ action: "stop" }) });Arranca un navegador con curl (paso 2) y pasa su cdpUrl al servidor MCP de Playwright. Las herramientas de navegador de tu asistente manejan entonces el Chrome alojado:
npx @playwright/mcp@latest --cdp-endpoint "wss://browsers.openwaf.dev/cdp/…"En la configuración de un cliente MCP:
{"mcpServers": {"browser": {"command": "npx",
"args": ["@playwright/mcp@latest", "--cdp-endpoint", "wss://browsers.openwaf.dev/cdp/…"]}}}El token CDP caduca a la hora. Para una tarea más larga, pide un cdpUrl nuevo con GET /v1/browsers/{id} y reinicia el servidor.
4. Para el navegador
Cerrar la conexión CDP no para el navegador: sigue sumando tiempo hasta que pasa 120 segundos sin ningún cliente CDP ni de vista en directo. Páralo cuando acabe la tarea:
curl -sS -X PATCH "https://browsers.openwaf.dev/v1/browsers/$ID" \
-H "X-API-Key: $OPENWAF_BROWSERS_KEY" -H "Content-Type: application/json" \
-d '{"action": "stop"}'Después consulta lo que ha dejado: la grabación (si la pediste) y las descargas, con enlaces que caducan.
curl -sS "https://browsers.openwaf.dev/v1/browsers/$ID/files" -H "X-API-Key: $OPENWAF_BROWSERS_KEY"Un miembro con rol tech o superior también puede parar cualquier navegador en marcha de la organización: Navegadores → Sesiones → Parar, openwaf-cloud ctl browsers sessions stop ID --reason "…" o la herramienta MCP browser_sessions_stop.