preview

Con preview un agente pone algo con interfaz web en un enlace público, para que lo abras desde tu teléfono o se lo envíes a alguien: un servidor de desarrollo que escucha en un puerto de la máquina del relay, o una carpeta de archivos sin más. También puede listar y cerrar las vistas previas de su propia conversación.

Pídelo con palabras normales: «arranca el servidor de desarrollo y dame un enlace», «enséñame el sitio compilado». Al agente se le indica que use la herramienta siempre que quieras ver, probar o compartir una interfaz web, y que nunca te mande a localhost.

Lo que ves #

• Una tarjeta de la vista previa en el panel de tareas en segundo plano de la conversación, con Open (Abrir), Copy link (Copiar enlace) y Close (Cerrar).
• Una tarjeta de enlace en la transcripción, en la respuesta en la que el agente la publicó. Muestra una insignia closed en cuanto la vista previa deja de existir. Una vista compartida de la conversación muestra solo la etiqueta de la tarjeta, nunca el enlace.
• Todas las vistas previas del relay, de todas las conversaciones, en Settings → Previews (Ajustes → Vistas previas), cada una con un botón para cerrarla.
• Una insignia offline en la tarjeta cuando el servidor de desarrollo que hay detrás de una vista previa de puerto deja de responder. El enlace sigue registrado: arranca el servidor de nuevo en el mismo puerto y el mismo enlace vuelve a funcionar.

Puedes hacer lo mismo sin agente escribiendo /preview en el área de redacción:

/preview 5173 web app        publish a port
/preview ./dist built site   publish a folder
/preview list                list the previews
/preview close               close one

Configurarlo #

Las vistas previas están desactivadas hasta que el operador del relay las configura. Necesitan un nombre de host propio, distinto del del relay, para que una app en vista previa nunca pueda llegar al propio relay. Tres cosas:

1. Un nombre de host que controles y que se distinga del del relay por el nombre, no solo por el puerto.
2. Un proxy frontal (Caddy, un Cloudflare Tunnel, …) que dirija ese nombre de host al puerto de las vistas previas.
3. Un bloque previews en el config.json del relay:

{
  "publicHostnames": ["relay.example.com"],
  "previews": {
    "enabled": true,
    "port": 3334,
    "bindHost": "127.0.0.1",
    "publicBaseUrl": "https://preview.example.com",
    "allowedTargetHosts": [],
    "maxLive": 8
  }
}

Los agentes tienen la herramienta tanto si esto está hecho como si no. Sin ello, una llamada create vuelve con el motivo, y al agente se le indica que te lo transmita: el arreglo le corresponde al operador.

Por proveedor #

Acciones #

Un resultado es JSON con "ok": true, o con "ok": false y un texto en error. La herramienta nunca falla de otra manera; un parámetro incorrecto vuelve como un error que el agente puede leer.

create #

Publica o un puerto o una carpeta, nunca ambos en una misma llamada. Nuevo en 0.9.11 Publicar de nuevo el mismo puerto o la misma carpeta en la misma conversación devuelve la vista previa que ya está activa, con el mismo enlace y la etiqueta sin cambios; el resultado dice entonces "existing": true.

Un servidor de desarrollo (port) #

El relay reenvía las peticiones a un servidor que escucha en ese puerto. No arranca, vigila ni reinicia ese servidor; eso sigue siendo una tarea en segundo plano normal del agente, con su propio botón de detener.

Cada vista previa vive bajo su propia ruta en el nombre de host de las vistas previas. El navegador pide /test_<token>/…; el relay quita ese prefijo antes de reenviar la petición y le comunica el prefijo a la app en X-Forwarded-Prefix. No reescribe las páginas. Así que una app funciona cuando los enlaces y las direcciones de recursos que envía son relativos o llevan el prefijo, mientras responde a peticiones sin el prefijo. Una app que pide /assets/app.js desde la raíz del host no lo encontrará.

Por eso al agente se le indica que llame a create primero y lea el basePath del resultado antes de arrancar el servidor de desarrollo.

{ "action": "create", "port": 5173, "label": "web app" }

{
  "ok": true,
  "existing": false,
  "url": "https://preview.example.com/test_0123456789abcdef0123456789abcdef/",
  "basePath": "/test_0123456789abcdef0123456789abcdef/",
  "token": "0123456789abcdef0123456789abcdef",
  "mode": "port",
  "hint": "Serve the app under /test_0123456789abcdef0123456789abcdef/ (the proxy strips the prefix and sends X-Forwarded-Prefix). Bind the dev server to 127.0.0.1, not 0.0.0.0: the relay's proxy reaches it there and nothing else should. Tell the user the URL and that the link is public."
}

Nuevo en 0.9.17 El hint también le indica al agente que vincule el servidor de desarrollo a 127.0.0.1, no a 0.0.0.0: el proxy del relay llega a él ahí, y nada más debería hacerlo. Solo las sesiones con la herramienta preview reciben esta línea (consulta Por proveedor). Los agentes a los que se les enseña la API de vistas previas en lugar de la herramienta no la reciben: GitHub Copilot y OpenAI con el motor SDK, y Grok y el motor de extensión de Copilot cuando el relay se ejecuta con OAR_MCP_SERVER=0.

Una carpeta (dir) #

El relay sirve él mismo los archivos de la carpeta. No tiene que ejecutarse nada: va bien para el resultado de una compilación, una maqueta, un único archivo HTML o un informe de cobertura.

• La carpeta tiene que estar dentro de la carpeta de trabajo de la conversación. Esto se vuelve a comprobar en cada petición, así que un enlace no puede hacerse apuntar fuera más tarde.
• Los archivos y carpetas cuyo nombre empieza por un punto (.git, .env) nunca se sirven, y tampoco los archivos de claves (*.pem, *.key, id_rsa…).
• Para la ruta de una carpeta se sirve index.html.
• Las rutas relativas de recursos funcionan tal cual. Las rutas desde la raíz del host (/assets/app.js) no.
• No hay conexiones WebSocket.

{ "action": "create", "dir": "./dist", "label": "built site" }

El resultado tiene los mismos campos, con "mode": "static".

list #

Lista las vistas previas de la propia conversación del agente, con token, label, url, target (la carpeta, o localhost:<port>), online y la conversación. Nuevo en 0.9.14 Antes de 0.9.14 la lista abarcaba todas las vistas previas del relay; el token de una vista previa es su única protección, así que ahora un agente solo ve las suyas. La lista de todo el relay es tuya, en Settings → Previews y con /preview list. Una vista previa que el relay no pudo comprobar tras un reinicio lleva "unverified": true y no se sirve hasta que la comprobación responde (consulta Después de un reinicio del relay).

{ "action": "list" }

{
  "ok": true,
  "enabled": true,
  "previews": [
    { "token": "0123456789abcdef0123456789abcdef", "label": "web app", "url": "https://preview.example.com/test_0123456789abcdef0123456789abcdef/", "target": "localhost:5173", "online": true, "conversationId": "3f9c…" }
  ]
}

close #

Cierra el enlace. Un servidor de desarrollo que haya detrás sigue ejecutándose.

Sin token y con varias vistas previas en la conversación, la llamada vuelve con un error y la lista entre la que elegir.

Nuevo en 0.9.14 Un agente solo cierra las vistas previas de su propia conversación. El token de la vista previa de otra conversación se rechaza:

{ "ok": false, "error": "This preview belongs to another conversation; a conversation can close only its own previews. The owner can close it in Settings → Previews." }

{ "action": "close", "token": "0123456789abcdef0123456789abcdef" }

{ "ok": true, "closed": { "token": "0123456789abcdef0123456789abcdef", "label": "web app" } }

Límites #

Las vistas previas se mantienen separadas del relay: se sirven en un puerto aparte, bajo un nombre de host aparte, donde no existe ninguna de las páginas ni la API del propio relay. Las vistas previas comparten ese nombre de host entre ellas, cada una bajo su propia ruta.