Vistas previas

Una vista previa pone algo con interfaz web en un enlace público: un servidor de desarrollo que escucha en un puerto de la máquina del relay, o una carpeta de archivos sin más. Abres el enlace desde cualquier dispositivo y puedes enviárselo a quien quieras. El relay no queda expuesto: las vistas previas las sirve un listener aparte en un nombre de host aparte.

Usos típicos:

• Abrir la app en tu teléfono. El agente arranca el servidor de desarrollo, tú tocas el enlace y pruebas el diseño en el dispositivo real.
• Enviarle un enlace a alguien. Un compañero abre una maqueta o un sitio compilado sin acceso a tu máquina ni a tu relay.
• Apuntar un webhook a un servidor de desarrollo. Un servicio que necesita una dirección pública puede llamar a la app que estás construyendo.

Esta página es la guía para propietarios y operadores. La herramienta del agente, con sus parámetros, resultados y límites, se describe en preview.

Cómo se mantienen las vistas previas separadas del relay #

Las vistas previas las sirve un segundo listener HTTP en su propio puerto, publicado en un nombre de host propio. De ahí se siguen dos cosas:

• El relay no está en ese puerto. Su API, su app web, su conexión en vivo y sus enlaces compartidos no están montados allí. El tráfico de las vistas previas no puede llegar a ellos, porque no existen en ese listener. Crear o cerrar una vista previa requiere el token de acceso del relay y solo ocurre en el propio puerto del relay.
• El nombre de host es distinto. Una app en vista previa se ejecuta en otro origen del navegador que el relay. Su JavaScript no puede enviar tu cookie de inicio de sesión del relay ni leer el almacenamiento de la app web del relay.

Tiene que cambiar el nombre de host, no solo el puerto. Las cookies ignoran los puertos, así que relay.example.com:3334 compartiría la cookie de inicio de sesión de relay.example.com. El relay se niega a arrancar la lane cuando los nombres de host coinciden.

Además, la lane nunca reenvía a una app en vista previa la cookie de inicio de sesión del relay (copilot_auth) ni una cabecera Authorization que contenga el token de acceso del relay, aunque una petición hecha a mano los lleve. La cabecera Authorization propia de una app pasa sin cambios.

Las vistas previas sí comparten un nombre de host entre ellas, cada una bajo su propia ruta. Consulta Lo que hay que tener en cuenta.

Configurarlo #

Las vistas previas están desactivadas hasta que el operador las configura. Son tres pasos.

1. Un nombre de host #

Elige un nombre de host que controles y cuyo nombre sea distinto del del relay, por ejemplo preview.example.com junto a relay.example.com. Apunta su DNS a tu proxy frontal o a tu túnel. Las vistas previas se separan por ruta, no por subdominio, así que basta con un único nombre de host de una etiqueta bajo una zona que ya tengas. En Cloudflare, ese nombre lo cubre el certificado Universal. Un comodín de dos etiquetas como *.preview.example.com no lo estaría, y por eso no hay un subdominio por vista previa.

2. Un proxy frontal #

El proxy envía el nombre de host de las vistas previas al listener de vistas previas, que por defecto usa el puerto del relay más uno (3334 cuando el relay usa 3333). Usa un puerto que fijes con previews.port; el proxy necesita un destino estable.

Caddy

preview.example.com {
    reverse_proxy 127.0.0.1:3334
}

Cloudflare Tunnel

Añade un segundo nombre de host público al túnel que ya usas, en el panel de Cloudflare en Public Hostnames → Add (Nombres de host públicos → Añadir) o en el config.yml del túnel:

ingress:
  - hostname: preview.example.com
    service: http://127.0.0.1:3334
  - hostname: relay.example.com
    service: http://127.0.0.1:3333
  - service: http_status:404

3. El bloque previews #

Añade el bloque al config.json del relay y reinicia el relay (consulta oar restart):

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

Cada clave, valor predeterminado y caso límite está en la tabla de config.json.

Sobrescrituras por entorno #

COPILOT_PREVIEWS_ENABLED, COPILOT_PREVIEWS_PORT, COPILOT_PREVIEWS_BIND_HOST, COPILOT_PREVIEWS_PUBLIC_BASE_URL y COPILOT_PREVIEWS_ALLOWED_TARGET_HOSTS sobrescriben las claves correspondientes. Sus valores y qué prevalece sobre qué están en Variables de entorno.

Cuando la lane se niega a arrancar #

Una lane mal configurada nunca tumba el relay. El relay sigue funcionando y la lane queda desactivada. Ninguna de estas comprobaciones se convierte en un aviso, porque cada una protege la separación descrita arriba.

Lo ves en dos sitios:

• El registro del relay, al arrancar: una línea PREVIEW LANE disabled: <message> por cada comprobación fallida. Cuando las comprobaciones pasan, el registro dice [preview] listener on http://127.0.0.1:3334 → https://preview.example.com. Dónde está el registro: Archivos y carpetas.
• La respuesta a una petición de publicación. La API responde 503 con Preview lane failed its startup checks y los mensajes en details. La herramienta preview del agente lo transmite, y al agente se le indica que te lo diga. Cuando previews.enabled no está fijado, la respuesta es Preview lane is disabled (set previews.enabled and previews.publicBaseUrl), y el registro no tiene ninguna línea.

Settings → Previews (Ajustes → Vistas previas) y el aviso de /preview no muestran el motivo. La pestaña de ajustes lista las vistas previas que existen, y el aviso solo dice que la publicación falló (consulta /preview). Mira en el registro del relay.

Si otro programa ocupa el puerto, las comprobaciones pasan, pero el listener no puede escuchar en él. El registro dice entonces PREVIEW LANE failed to bind :<port> — <reason>. Para la API, la lane está activa, pero nada responde en el puerto de vistas previas, así que los enlaces no se abren. Libera el puerto o fija otro previews.port.

Tres formas de publicar #

Pedírselo al agente #

Di lo que quieres: «arranca el servidor de desarrollo y dame un enlace», «enséñame el sitio compilado». El agente usa la herramienta preview, o la API de vistas previas del relay cuando un proveedor no tiene la herramienta. Te da el enlace y te dice que es público. Qué proveedores tienen la herramienta está en la tabla de la página de referencia.

/preview en el área de redacción #

El comando se ejecuta en tu navegador contra el relay. Funciona con todos los proveedores y no cuesta ningún turn del agente. Se ejecuta cuando no hay nada adjunto al mensaje. El aviso aparece en la conversación.

Una primera palabra formada por dígitos es siempre un puerto, y un puerto fuera del rango 1 a 65535 imprime la línea de uso. Para una carpeta llamada 8080, escribe ./8080.

Si la publicación falla, el aviso es el mismo para todas las causas (un puerto incorrecto, una carpeta fuera de la carpeta de trabajo, una lane llena, una lane desactivada):

Preview failed — check the port/path, or whether the preview lane is enabled (Settings → Live previews).

El motivo exacto no se muestra. La lista está en Settings → Previews, bajo el encabezado Live previews (Vistas previas en vivo). Para ver el motivo, llama a la API (abajo) o mira la tabla de Solución de problemas. Si no se puede llegar al relay, el aviso es Preview command failed — could not reach the relay. El menú de comandos y sus teclas están en El área de redacción.

La API #

Todo lo anterior usa la misma API en el puerto del relay. Necesita el token de acceso del relay (authToken en config.json, el mismo token con el que inicias sesión) como bearer token. Regístrala primero, para conocer la ruta base, y luego arranca el servidor de desarrollo bajo ella:

curl -sX POST http://127.0.0.1:3333/api/previews \
  -H "authorization: Bearer $RELAY_TOKEN" -H 'content-type: application/json' \
  -d '{"conversationId":"<conversation id>","port":5173,"label":"web app"}'

{
  "ok": true,
  "url": "https://preview.example.com/test_0123456789abcdef0123456789abcdef/",
  "basePath": "/test_0123456789abcdef0123456789abcdef/",
  "preview": { "token": "0123456789abcdef0123456789abcdef" },
  "existing": false
}

existing es true cuando la conversación ya tenía una vista previa activa del mismo puerto o carpeta y te devolvió esa.

Hacer que una app funcione bajo la ruta de la vista previa #

Cada vista previa vive bajo /test_<token>/ en el nombre de host compartido de las vistas previas. La regla que se deriva de lo que hace el proxy:

• El navegador pide /test_<token>/….
• La app recibe la ruta sin ese prefijo.
• Así que la app debe poner en sus páginas enlaces y URL de recursos que lleven el prefijo o sean relativos, y aun así debe responder a peticiones que no lo lleven.

Lo que hace el proxy por el camino:

No reescribe el cuerpo de páginas, hojas de estilo ni scripts. Una app que escribe /assets/app.js en su HTML lo pide a la raíz del nombre de host de las vistas previas, donde no vive ninguna vista previa, y el navegador recibe la página No such preview (404). Esa es la señal de que la app no conoce su prefijo.

Lo que funciona #

• URL relativas. Una app cuyas páginas usan direcciones del estilo ./assets/app.js funciona tal cual: la página está en /test_<token>/, así que se resuelven dentro de la vista previa. Esto se deriva de cómo funciona el proxy; no se probó framework por framework.
• Leer el prefijo. Una app que enruta por rutas sin prefijo y construye sus enlaces a partir de X-Forwarded-Prefix cumple la regla exactamente.
• Un sitio compilado. Compila con una base relativa o igual al prefijo y luego publica la carpeta de salida como vista previa estática. Las peticiones de /test_<token>/assets/… se sirven desde la carpeta, así que funcionan los dos tipos de URL.

Lo que no funciona tal cual #

Un ajuste de la herramienta que hace que la app responda solo a peticiones que llevan el prefijo no encaja, porque el proxy lo quita.

• Servidor de desarrollo de Vite con base fijado al prefijo (--base). Comprobado contra el código fuente de Vite 8.3.1 en la máquina del relay: el servidor de desarrollo solo atiende rutas que empiezan por base. Responde a una petición de / con una redirección a base, que el proxy deja como está, así que el navegador entra en un bucle. Las demás peticiones sin prefijo reciben un 404 que dice que el servidor tiene una URL base pública. La recarga en caliente solo escucha en la ruta bajo base, con la que no coincide la petición recortada. Usa el enfoque del sitio compilado, o una configuración de Vite que sirva desde la raíz con URL relativas.
• Express con el router montado en el prefijo (app.use(prefix, router)). La app recibe /x, no /test_<token>/x, así que el montaje no coincide. Monta el router en / y construye los enlaces a partir de X-Forwarded-Prefix.

Next.js (basePath, assetPrefix) y SvelteKit (kit.paths.base) se mencionan en las notas propias de OAR para los agentes, pero esas notas no se comprobaron contra lo que hace el proxy, y ninguna de las dos herramientas está disponible aquí para probarla. Si su ajuste de base hace que la app espere el prefijo en cada petición, no encaja por la misma razón que Vite. Sin verificar: pruébalo antes de confiar en ello.

Vistas previas estáticas #

Con dir en lugar de port, el propio relay sirve una carpeta. No tiene que ejecutarse nada, lo que encaja con una salida de compilación, una maqueta, un único archivo HTML o un informe de cobertura.

• La carpeta se toma de la carpeta de trabajo de la conversación (absoluta, o relativa a ella) y debe estar dentro de ella. Una vista previa publicada sin conversación usa la propia carpeta de trabajo del relay. Esto se comprueba al publicar y en cada petición, así que un enlace simbólico creado más tarde no puede llevar fuera.
• Para una ruta de carpeta se sirve index.html. No se almacena nada en caché.
• Nunca se sirven: archivos y carpetas cuyo nombre empieza por un punto (.git, .env) ni archivos de claves (*.pem, *.key, nombres que empiezan por id_rsa, id_ed25519, id_ecdsa o id_dsa).
• Las rutas relativas de recursos funcionan. También las que empiezan por el prefijo de la vista previa. Las absolutas desde la raíz (/assets/app.js), no.
• Una carpeta sin index.html, y cualquier archivo que falte, recibe una página Not found (404).
• Una vista previa estática está siempre online y rechaza las conexiones WebSocket.

Gestionar las vistas previas #

• La tarjeta en el panel de tareas en segundo plano. Cada vista previa de la conversación tiene una tarjeta con su etiqueta, el puerto, una nota de que el enlace es público, una insignia online u offline cuando el relay la ha comprobado, y los botones Open (Abrir), Copy link (Copiar enlace) y Close (Cerrar). El panel se describe en Tareas en segundo plano.
• Una tarjeta de enlace en la transcripción. Cuando se publica una vista previa mientras corre un turn de la conversación, la respuesta lleva una tarjeta de enlace, la haya publicado el agente o tú con /preview. Una vista previa publicada entre turns no tiene tarjeta en la transcripción. Cuando la vista previa ya no existe, la tarjeta muestra una insignia closed y ningún enlace. Una conversación compartida muestra la tarjeta solo con su etiqueta, y cada enlace de vista previa citado en su texto dice [preview link removed].
• Settings → Previews. La lista Live previews muestra todas las vistas previas del relay, de todas las conversaciones, con los 8 primeros caracteres del id de la conversación y Nuevo en 0.9.11 cuándo se publicó y cuándo se abrió por última vez. Cierra una aquí cuando hayas salido de su conversación. Consulta Ajustes.

offline y closed son cosas distintas. El relay comprueba cada vista previa de puerto cada 15 segundos, intentando conectarse al puerto (y una vez de inmediato al publicar). Cuando nada responde, la tarjeta muestra una insignia offline y la nota «offline — dev server not responding». El enlace sigue siendo válido: vuelve a arrancar el servidor en el mismo puerto y el mismo enlace funciona. closed significa que la vista previa ya no existe y el enlace ya no se resuelve.

Cerrar una vista previa solo termina el enlace. El servidor de desarrollo sigue ejecutándose como la tarea en segundo plano que es.

Una vista previa no caduca sola. Termina cuando la cierras, o Nuevo en 0.9.11 cuando eliminas su conversación (también mediante una reconstrucción de la caché del relay). Archivar una conversación mantiene activas sus vistas previas, en Settings → Previews.

Publicar de nuevo el mismo puerto o carpeta en la misma conversación devuelve la vista previa que ya está activa, con el mismo enlace y la etiqueta sin cambios, en lugar de una nueva.

Como máximo hay 8 vistas previas activas a la vez, para todo el relay (previews.maxLive). El rechazo nombra las tres más antiguas, con cuándo se publicó y se abrió por última vez cada una, y cómo cerrarlas.

Después de un reinicio del relay Nuevo en 0.9.11 #

Las vistas previas sobreviven a un reinicio del relay, a una actualización o a un fallo: el relay las guarda en su base de datos y las restaura al arrancar, así que un enlace que hayas repartido sigue funcionando. Cada una se comprueba antes de nuevo, y termina cuando la comprobación determina que ya no es válida:

• una vista previa de carpeta cuya carpeta ya no existe, o ya no está dentro de la carpeta de trabajo de su conversación;
• una vista previa de puerto después de reiniciar la máquina: el servidor de desarrollo ya no existe, y el puerto puede pertenecer más adelante a otra cosa;
• una vista previa cuya conversación ya no existe.

Linux y macOS informan de un reinicio de forma fiable. En Windows, un Restart (Reiniciar) cuenta como tal, pero con fast startup (inicio rápido) activado (el valor predeterminado de Windows), Shut down (Apagar) y volver a encender no: una vista previa de puerto de antes vuelve y llega a lo que escuche entonces en su puerto. Cierra las vistas previas que ya no necesites.

Una comprobación que no puede responder, porque la base de datos está ocupada o la carpeta no se puede leer por otro motivo que no sea que ya no existe, no termina la vista previa. Mientras tanto no se sirve: Settings → Previews y el list de la herramienta la muestran como no servida (unverified), cuenta para el límite y se puede cerrar. El relay la vuelve a comprobar cada 15 segundos y la sirve de nuevo bajo su enlace en cuanto la comprobación responde; publicar de nuevo el mismo puerto o carpeta en su conversación lo hace al instante. Tras diez minutos sin respuesta, la vista previa termina, y el registro lo indica.

Una vista previa de puerto también se sondea una vez justo después del arranque, para que su insignia online u offline esté al día. El registro del relay nombra una vista previa por un hash corto, nunca por su token. Consulta también Lo que conserva y lo que pierde un reinicio.

WebSockets #

Una vista previa de puerto deja pasar las conexiones WebSocket bajo el mismo prefijo, quitándolo como en cualquier petición, así que los sockets propios de una app funcionan cuando el navegador se conecta a través del enlace de la vista previa. (La recarga en caliente es cosa de la app: consulta la nota sobre Vite de arriba.) Una vista previa estática, y un enlace desconocido o cerrado, responden a una petición WebSocket con 404. Si la app responde al upgrade con una respuesta normal, el navegador recibe ese estado. Si la app no está en marcha, 502.

Lo que hay que tener en cuenta #

• Las vistas previas comparten origen entre ellas. Las cookies se acotan a la ruta de cada vista previa y los tokens no se pueden adivinar, pero dos vistas previas no están tan separadas entre sí como lo está cada una del relay.
• Solo tu propia máquina, por defecto. Una vista previa de puerto solo puede apuntar a direcciones de loopback, más los hosts de previews.allowedTargetHosts. Los propios puertos del relay siempre se rechazan, ya que publicar uno pondría la página de inicio de sesión del relay en el nombre de host público.
• El relay no ejecuta la app. Nunca arranca ni reinicia un servidor de desarrollo. Si el servidor se detiene, la tarjeta pasa a offline.

Por proveedor #

Las vistas previas se ven igual en todos los proveedores; solo cambia la forma en que publica un agente, como muestra la página de referencia. /preview y Settings → Previews funcionan con todos ellos.

Solución de problemas #