# Inicio rápido

> Crea una clave de navegador, arranca un Chrome en browsers.openwaf.dev y manéjalo con curl, Playwright, Puppeteer o el servidor MCP de Playwright.

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](https://developers.openwaf.dev/es/browsers/#get-access).
- **Un `admin` de toda la organización** para crear claves. Para ver el uso y las sesiones basta `readonly`.
- **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).

**Panel**

1. Abre **Navegadores** en el menú de la organización y después la pestaña **Claves**.
2. Elige **Crear clave** y ponle un nombre, por ejemplo `ci-agent` (minúsculas, dígitos y guiones).
3. Copia el secreto ahora. No lo volverás a ver.

**CLI**

```sh
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](https://developers.openwaf.dev/es/cli/get-started/) para la dirección de la API y el token.
**API**

```sh
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`:

```json
{"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_…"}
```
**MCP**

Pide a tu asistente, conectado al [servidor MCP de OpenWAF](https://developers.openwaf.dev/es/mcp/connect/) 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`:

```sh
read -rs OPENWAF_BROWSERS_KEY && export OPENWAF_BROWSERS_KEY   # pega bdk_…
```

## 2. Arranca un navegador

```sh
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:

```json
{"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](https://developers.openwaf.dev/es/browsers/reference/#data-plane-errors).

## 3. Manéjalo

**Playwright**

```ts
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" }) });
```
**Puppeteer**

```ts
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" }) });
```
**Playwright MCP**

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:

```sh
npx @playwright/mcp@latest --cdp-endpoint "wss://browsers.openwaf.dev/cdp/…"
```

En la configuración de un cliente MCP:

```json
{"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:

```sh
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.

```sh
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`.

## Siguientes pasos

- [Referencia de la API](https://developers.openwaf.dev/es/browsers/reference/): cada campo de `POST /v1/browsers`, perfiles, archivos y el registro de salida.
- [Límites y cuotas](https://developers.openwaf.dev/es/browsers/limits/): qué pasa al 80 % y al 100 % de la cuota.
- [Web Bot Auth](https://developers.openwaf.dev/es/browsers/web-bot-auth/): qué dice la firma a los sitios y cómo desactivarla para un navegador.