Previews

Eine Preview stellt etwas mit einer Weboberfläche unter einen öffentlichen Link: einen Dev-Server, der auf einem Port des Relay-Rechners lauscht, oder einen Ordner mit einfachen Dateien. Du öffnest den Link von jedem Gerät aus und kannst ihn an jeden schicken. Das Relay wird dabei nicht offengelegt: Previews liefert ein eigener Listener unter einem eigenen Hostnamen aus.

Typische Einsätze:

• Die App auf dem Handy öffnen. Der Agent startet den Dev-Server, du tippst auf den Link und probierst das Layout auf dem echten Gerät aus.
• Jemandem einen Link schicken. Eine Kollegin öffnet ein Mockup oder eine gebaute Website ohne Zugriff auf deinen Rechner oder dein Relay.
• Einen Webhook auf einen Dev-Server richten. Ein Dienst, der eine öffentliche Adresse braucht, kann die App aufrufen, die du gerade baust.

Diese Seite ist die Anleitung für Besitzer und Betreiber. Das Tool des Agents mit seinen Parametern, Ergebnissen und Grenzen ist unter preview beschrieben.

Wie Previews vom Relay getrennt bleiben #

Previews liefert ein zweiter HTTP-Listener auf einem eigenen Port aus, veröffentlicht unter einem eigenen Hostnamen. Daraus folgt zweierlei:

• Das Relay ist nicht auf diesem Port. Seine API, seine Web-App, seine Live-Verbindung und seine Teilen-Links sind dort nicht eingehängt. Preview-Verkehr kann sie nicht erreichen, weil es sie auf diesem Listener nicht gibt. Eine Preview anlegen oder schließen braucht das Zugriffstoken des Relays und geschieht nur auf dem eigenen Port des Relays.
• Der Hostname ist ein anderer. Eine App in der Preview läuft in einem anderen Browser-Origin als das Relay. Ihr JavaScript kann dein Anmelde-Cookie für das Relay nicht mitschicken und den Speicher der Relay-Web-App nicht lesen.

Der Hostname muss sich unterscheiden, nicht nur der Port. Cookies ignorieren Ports, also würde relay.example.com:3334 das Anmelde-Cookie von relay.example.com teilen. Das Relay weigert sich, die Lane zu starten, wenn die Hostnamen übereinstimmen.

Zusätzlich leitet die Lane nie das Anmelde-Cookie des Relays (copilot_auth) oder einen Authorization-Header mit dem Zugriffstoken des Relays an eine App in der Preview weiter, auch nicht, wenn eine handgemachte Anfrage sie mitbringt. Der eigene Authorization-Header einer App geht durch.

Untereinander teilen sich Previews einen Hostnamen, jede unter ihrem eigenen Pfad. Siehe Was du beachten solltest.

Einrichten #

Previews sind aus, bis der Betreiber sie einrichtet. Es sind drei Schritte.

1. Ein Hostname #

Wähl einen Hostnamen, über den du verfügst und der sich im Namen von dem des Relays unterscheidet, zum Beispiel preview.example.com neben relay.example.com. Richte sein DNS auf deinen vorgelagerten Proxy oder Tunnel. Previews werden über den Pfad getrennt, nicht über Subdomains, also reicht ein einziger Hostname eine Ebene unter einer Zone, die du schon hast. Bei Cloudflare deckt das Universal-Zertifikat diesen Namen ab. Ein Wildcard über zwei Ebenen wie *.preview.example.com wäre nicht abgedeckt; deshalb gibt es keine Subdomain pro Preview.

2. Ein vorgelagerter Proxy #

Der Proxy leitet den Preview-Hostnamen an den Preview-Listener, der standardmäßig auf dem Port des Relays plus eins lauscht (3334, wenn das Relay 3333 nutzt). Nimm einen Port, den du mit previews.port festlegst; der Proxy braucht ein stabiles Ziel.

Caddy

preview.example.com {
    reverse_proxy 127.0.0.1:3334
}

Cloudflare Tunnel

Füge dem Tunnel, den du schon nutzt, einen zweiten öffentlichen Hostnamen hinzu (im Cloudflare-Dashboard unter Public Hostnames → Add oder in der config.yml des Tunnels):

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. Der Block previews #

Füge den Block in die config.json des Relays ein und starte das Relay neu (siehe oar restart):

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

Jeden Key, jeden Standardwert und jeden Sonderfall findest du in der Tabelle auf config.json.

Überschreiben per Umgebung #

COPILOT_PREVIEWS_ENABLED, COPILOT_PREVIEWS_PORT, COPILOT_PREVIEWS_BIND_HOST, COPILOT_PREVIEWS_PUBLIC_BASE_URL und COPILOT_PREVIEWS_ALLOWED_TARGET_HOSTS überschreiben die passenden Keys. Ihre Werte und was Vorrang vor was hat, stehen unter Umgebungsvariablen.

Wenn die Lane nicht startet #

Eine falsch eingerichtete Lane legt nie das Relay lahm. Das Relay läuft weiter, und die Lane bleibt aus. Keine dieser Prüfungen wird zu einer bloßen Warnung, weil jede die oben beschriebene Trennung schützt.

Du siehst das an zwei Stellen:

• Im Log des Relays, beim Start: eine Zeile PREVIEW LANE disabled: <message> pro gescheiterter Prüfung. Bestehen die Prüfungen, sagt das Log [preview] listener on http://127.0.0.1:3334 → https://preview.example.com. Wo das Log liegt: Dateien und Ordner.
• In der Antwort auf eine Veröffentlichungsanfrage. Die API antwortet mit 503 und Preview lane failed its startup checks sowie den Meldungen in details. Das preview-Tool des Agents gibt das weiter, und der Agent wird angewiesen, es dir zu sagen. Ist previews.enabled nicht gesetzt, lautet die Antwort Preview lane is disabled (set previews.enabled and previews.publicBaseUrl), und das Log hat keine Zeile.

Settings → Previews (Einstellungen → Previews) und der Hinweis von /preview zeigen den Grund nicht. Der Einstellungs-Tab listet die vorhandenen Previews, und der Hinweis sagt nur, dass die Veröffentlichung gescheitert ist (siehe /preview). Schau ins Log des Relays.

Ist der Port von einem anderen Programm belegt, bestehen die Prüfungen, aber der Listener kann nicht binden. Das Log sagt dann PREVIEW LANE failed to bind :<port> — <reason>. Für die API ist die Lane aktiv, aber auf dem Preview-Port antwortet nichts, also öffnen sich die Links nicht. Gib den Port frei oder setz einen anderen previews.port.

Drei Wege zu veröffentlichen #

Den Agent bitten #

Sag, was du willst: „Starte den Dev-Server und gib mir einen Link“, „Zeig mir die gebaute Website“. Der Agent nutzt das preview-Tool oder, wo ein Provider kein Tool hat, die Preview-API des Relays. Er nennt dir den Link und dass der Link öffentlich ist. Welche Provider das Tool haben, steht in der Tabelle auf der Referenzseite.

/preview im Eingabebereich #

Der Befehl läuft in deinem Browser gegen das Relay. Er funktioniert mit jedem Provider und kostet keinen Agent-Turn. Er läuft, wenn nichts an die Nachricht angehängt ist. Der Hinweis erscheint in der Konversation.

Ein erstes Wort aus Ziffern ist immer ein Port, und ein Port außerhalb von 1 bis 65535 gibt die Nutzungszeile aus. Für einen Ordner namens 8080 tippe ./8080.

Scheitert die Veröffentlichung, ist der Hinweis bei jeder Ursache derselbe (ein falscher Port, ein Ordner außerhalb des Arbeitsordners, eine volle Lane, eine abgeschaltete Lane):

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

Der genaue Grund wird nicht gezeigt. Die Liste steht unter Settings → Previews, unter der Überschrift Live previews (Live-Previews). Um den Grund zu sehen, ruf die API auf (unten) oder sieh in der Tabelle unter Fehlerbehebung nach. Ist das Relay nicht erreichbar, lautet der Hinweis Preview command failed — could not reach the relay. Das Befehlsmenü und seine Tasten stehen unter Eingabebereich.

Die API #

Alles oben nutzt dieselbe API auf dem Port des Relays. Sie braucht das Zugriffs-Token des Relays (authToken in config.json, dasselbe Token, mit dem du dich anmeldest) als Bearer-Token. Registriere zuerst, damit du den Basispfad kennst, und starte dann den Dev-Server darunter:

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 ist true, wenn die Konversation schon eine aktive Preview desselben Ports oder Ordners hatte und du diese zurückbekommen hast.

Eine App unter dem Pfad der Preview lauffähig machen #

Jede Preview liegt unter /test_<token>/ auf dem gemeinsamen Preview-Hostnamen. Die Regel, die aus dem folgt, was der Proxy tut:

• Der Browser fragt nach /test_<token>/….
• Die App bekommt den Pfad ohne dieses Präfix.
• Also muss die App in ihre Seiten Links und Asset-URLs schreiben, die entweder das Präfix tragen oder relativ sind, und sie muss trotzdem auf Anfragen antworten, die es nicht tragen.

Was der Proxy unterwegs tut:

Er schreibt nicht den Inhalt von Seiten, Stylesheets oder Skripten um. Eine App, die /assets/app.js in ihr HTML schreibt, fragt die Wurzel des Preview-Hostnamens, wo keine Preview liegt, und der Browser bekommt die Seite No such preview (404). Daran erkennst du, dass die App ihr Präfix nicht kennt.

Was funktioniert #

• Relative URLs. Eine App, deren Seiten Adressen im Stil von ./assets/app.js nutzen, funktioniert, wie sie ist: Die Seite liegt unter /test_<token>/, also werden sie innerhalb der Preview aufgelöst. Das folgt aus der Arbeitsweise des Proxys; es wurde nicht pro Framework ausprobiert.
• Das Präfix auslesen. Eine App, die auf Pfaden ohne Präfix routet und ihre Links aus X-Forwarded-Prefix baut, passt genau zur Regel.
• Eine gebaute Website. Bau mit einer Basis, die relativ ist oder dem Präfix entspricht, und veröffentliche dann den Ausgabeordner als statische Preview. Anfragen nach /test_<token>/assets/… werden aus dem Ordner bedient, also funktionieren beide Arten von URL.

Was so nicht funktioniert #

Eine Tool-Einstellung, die die App nur auf Anfragen mit Präfix antworten lässt, passt nicht, weil der Proxy das Präfix entfernt.

• Vite-Dev-Server mit base auf dem Präfix (--base). Geprüft am Quellcode von Vite 8.3.1 auf dem Rechner des Relays: Der Dev-Server bearbeitet nur Pfade, die mit base beginnen. Auf eine Anfrage nach / antwortet er mit einer Umleitung auf base, die der Proxy unverändert lässt, also dreht sich der Browser im Kreis. Andere Anfragen ohne Präfix bekommen ein 404, das sagt, der Server habe eine „public base URL“. Hot Reload lauscht nur auf dem Pfad unter base, zu dem die gekürzte Anfrage nicht passt. Nutze den Weg über die gebaute Website oder ein Vite-Setup, das von der Wurzel aus mit relativen URLs ausliefert.
• Express mit dem Router auf dem Präfix eingehängt (app.use(prefix, router)). Die App bekommt /x, nicht /test_<token>/x, also passt das Einhängen nicht. Häng den Router auf / ein und bau Links aus X-Forwarded-Prefix.

Next.js (basePath, assetPrefix) und SvelteKit (kit.paths.base) werden in OARs eigenen Hinweisen für Agents genannt, aber diese Hinweise wurden nicht gegen das geprüft, was der Proxy tut, und keins der beiden Tools ist hier zum Testen verfügbar. Lässt ihre Basis-Einstellung die App das Präfix bei jeder Anfrage erwarten, passt sie aus demselben Grund nicht wie Vite. Nicht verifiziert: Probier es aus, bevor du dich darauf verlässt.

Statische Previews #

Mit dir statt port liefert das Relay einen Ordner selbst aus. Nichts muss laufen; das passt für eine Build-Ausgabe, ein Mockup, eine einzelne HTML-Datei oder einen Coverage-Bericht.

• Der Ordner wird vom Arbeitsordner der Konversation aus genommen (absolut oder relativ dazu) und muss darin liegen. Eine Preview, die ohne Konversation veröffentlicht wird, nutzt den eigenen Arbeitsordner des Relays. Das wird beim Veröffentlichen und bei jeder Anfrage geprüft, sodass ein später angelegter Symlink nicht hinausführen kann.
• Für einen Ordnerpfad wird index.html ausgeliefert. Nichts wird gecacht.
• Nie ausgeliefert: Dateien und Ordner, deren Name mit einem Punkt beginnt (.git, .env), und Schlüsseldateien (*.pem, *.key, Namen, die mit id_rsa, id_ed25519, id_ecdsa oder id_dsa beginnen).
• Relative Asset-Pfade funktionieren. Ebenso solche, die mit dem Präfix der Preview beginnen. Wurzel-absolute (/assets/app.js) nicht.
• Ein Ordner ohne index.html und jede fehlende Datei bekommen eine Seite Not found (404).
• Eine statische Preview ist immer online und lehnt WebSocket-Verbindungen ab.

Previews verwalten #

• Die Karte in der Leiste der Hintergrund-Tasks. Jede Preview der Konversation hat eine Karte mit ihrem Label, dem Port, einem Hinweis, dass der Link öffentlich ist, einem Badge online oder offline, sobald das Relay sie geprüft hat, und den Buttons Open (Öffnen), Copy link (Link kopieren) und Close (Schließen). Die Leiste ist unter Hintergrund-Tasks beschrieben.
• Eine Link-Karte im Verlauf. Wird eine Preview veröffentlicht, während ein Turn der Konversation läuft, trägt die Antwort eine Link-Karte, egal ob der Agent oder du mit /preview sie veröffentlicht hat. Eine Preview, die zwischen Turns veröffentlicht wird, hat keine Karte im Verlauf. Ist die Preview weg, zeigt die Karte ein Badge closed und keinen Link. Eine geteilte Konversation zeigt die Karte nur mit ihrem Label, und jeder Preview-Link, der in ihrem Text zitiert ist, lautet [preview link removed].
• Settings → Previews. Die Liste Live previews zeigt jede Preview des Relays aus allen Konversationen, mit den ersten 8 Zeichen der Konversations-ID und Neu in 0.9.11 wann sie veröffentlicht und zuletzt geöffnet wurde. Schließ hier eine, wenn du ihre Konversation verlassen hast. Siehe Settings.

offline und closed sind verschieden. Das Relay prüft jede Port-Preview alle 15 Sekunden, indem es versucht, sich mit dem Port zu verbinden (und einmal sofort beim Veröffentlichen). Antwortet nichts, zeigt die Karte ein Badge offline und den Hinweis „offline — dev server not responding“. Der Link bleibt gültig: Starte den Server wieder auf demselben Port, und derselbe Link funktioniert. closed heißt, die Preview ist weg und der Link führt nirgends mehr hin.

Eine Preview zu schließen, beendet nur den Link. Der Dev-Server läuft als der Hintergrund-Task weiter, der er ist.

Eine Preview läuft nicht von selbst ab. Sie endet, wenn du sie schließt, oder Neu in 0.9.11 wenn du ihre Konversation löschst (auch über einen Neuaufbau des Caches des Relays). Eine Konversation zu archivieren, lässt ihre Previews aktiv, in Settings → Previews.

Veröffentlichst du denselben Port oder Ordner in derselben Konversation noch einmal, bekommst du die schon aktive Preview zurück, mit demselben Link und unverändertem Label, statt einer neuen.

Höchstens 8 Previews sind gleichzeitig aktiv, für das ganze Relay (previews.maxLive). Die Ablehnung nennt die drei ältesten, jeweils mit dem Zeitpunkt der Veröffentlichung und des letzten Öffnens, und wie man sie schließt.

Nach einem Relay-Neustart Neu in 0.9.11 #

Previews überstehen einen Neustart des Relays, ein Update oder einen Absturz: Das Relay hält sie in seiner Datenbank und stellt sie beim Start wieder her, sodass ein Link, den du weitergegeben hast, weiter funktioniert. Jede wird vorher erneut geprüft und endet, wenn die Prüfung sie nicht mehr für gültig befindet:

• eine Ordner-Preview, deren Ordner weg ist oder nicht mehr im Arbeitsordner ihrer Konversation liegt;
• eine Port-Preview nach einem Neustart des Rechners: Der Dev-Server ist weg, und der Port gehört später vielleicht etwas anderem;
• eine Preview, deren Konversation nicht mehr existiert.

Linux und macOS melden einen Neustart zuverlässig. Unter Windows zählt Restart (Neu starten) als einer, aber mit eingeschaltetem fast startup (Schnellstart; Windows-Standard) zählt Shut down (Herunterfahren) und Wiedereinschalten nicht: Eine Port-Preview von vorher kommt zurück und erreicht dann, was auch immer auf ihrem Port lauscht. Schließ Previews, die du nicht mehr brauchst.

Eine Prüfung, die keine Antwort geben kann, weil die Datenbank beschäftigt ist oder der Ordner aus einem anderen Grund als seinem Verschwinden nicht lesbar ist, beendet die Preview nicht. Sie wird solange nicht ausgeliefert: Settings → Previews und list des Tools zeigen sie als nicht ausgeliefert (unverified), sie zählt zum Limit, und sie lässt sich schließen. Das Relay prüft sie alle 15 Sekunden erneut und liefert sie wieder unter ihrem Link aus, sobald die Prüfung eine Antwort gibt; denselben Port oder Ordner in ihrer Konversation erneut zu veröffentlichen, bewirkt das sofort. Nach zehn Minuten ohne Antwort endet die Preview, und das Log sagt es.

Eine Port-Preview wird außerdem gleich nach dem Start einmal geprüft, damit ihr Badge online oder offline aktuell ist. Das Log des Relays nennt eine Preview mit einem kurzen Hash, nie mit ihrem Token. Siehe auch Was ein Neustart behält und was er verliert.

WebSockets #

Eine Port-Preview reicht WebSocket-Verbindungen unter demselben Präfix durch, mit entferntem Präfix wie bei jeder Anfrage, sodass die eigenen Sockets einer App funktionieren, wenn sich der Browser über den Preview-Link verbindet. (Hot Reload ist Sache der App: siehe den Vite-Hinweis oben.) Eine statische Preview sowie ein unbekannter oder geschlossener Link beantworten eine WebSocket-Anfrage mit 404. Antwortet die App auf das Upgrade mit einer gewöhnlichen Antwort, bekommt der Browser diesen Status. Ist die App nicht erreichbar, 502.

Was du beachten solltest #

• Previews teilen sich untereinander einen Origin. Cookies sind auf den Pfad jeder Preview begrenzt, und die Tokens lassen sich nicht erraten, aber zwei Previews sind nicht so streng voneinander getrennt wie jede vom Relay.
• Standardmäßig nur dein eigener Rechner. Eine Port-Preview darf nur auf Loopback-Adressen zeigen, plus die Hosts in previews.allowedTargetHosts. Die eigenen Ports des Relays werden immer abgelehnt, weil deren Veröffentlichung die Anmeldeseite des Relays auf den öffentlichen Hostnamen stellen würde.
• Das Relay betreibt die App nicht. Es startet einen Dev-Server nie und startet ihn nie neu. Hält der Server an, wechselt die Karte auf offline.

Nach Provider #

Previews sehen bei jedem Provider gleich aus; nur der Weg, auf dem ein Agent veröffentlicht, unterscheidet sich, wie die Referenzseite zeigt. /preview und Settings → Previews funktionieren mit allen.

Fehlerbehebung #