preview

Mit preview stellt ein Agent etwas mit einer Weboberfläche unter einen öffentlichen Link, damit du es vom Handy aus öffnen oder an jemanden schicken kannst: einen Dev-Server, der auf einem Port des Relay-Rechners lauscht, oder einen Ordner mit einfachen Dateien. Es kann außerdem die Previews seiner eigenen Konversation auflisten und schließen.

Frag in einfachen Worten: „Starte den Dev-Server und gib mir einen Link“, „Zeig mir die gebaute Website“. Der Agent wird angewiesen, das Tool immer zu nutzen, wenn du eine Weboberfläche sehen, ausprobieren oder teilen willst, und dich nie auf localhost zu verweisen.

Was du siehst #

• Eine Karte für die Preview in der Task-Leiste der Konversation, mit Open (Öffnen), Copy link (Link kopieren) und Close (Schließen).
• Eine Link-Karte im Verlauf, an der Antwort, in der der Agent sie veröffentlicht hat. Sie zeigt ein Badge closed, sobald die Preview weg ist. Eine geteilte Ansicht der Konversation zeigt nur die Beschriftung der Karte, nie den Link.
• Jede Preview des Relays, über alle Konversationen hinweg, unter Settings → Previews (Einstellungen → Previews), jede mit einem Button zum Schließen.
• Ein Badge offline auf der Karte, wenn der Dev-Server hinter einer Port-Preview nicht mehr antwortet. Der Link bleibt registriert: Starte den Server erneut auf demselben Port, und derselbe Link funktioniert wieder.

Dasselbe geht ohne Agent, indem du /preview in den Eingabebereich tippst:

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

Einrichten #

Previews sind aus, bis der Betreiber des Relays sie einrichtet. Sie brauchen einen eigenen Hostnamen, getrennt von dem des Relays, damit eine App in der Preview das Relay selbst nie erreichen kann. Drei Dinge:

1. Einen Hostnamen, den du kontrollierst und der sich vom Relay im Namen unterscheidet, nicht nur im Port.
2. Einen vorgeschalteten Proxy (Caddy, ein Cloudflare Tunnel, …), der diesen Hostnamen auf den Preview-Port richtet.
3. Einen Block previews in der config.json des Relays:

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

Agents haben das Tool, ob das erledigt ist oder nicht. Ohne Einrichtung kommt ein Aufruf von create mit dem Grund zurück, und der Agent wird angewiesen, ihn an dich weiterzugeben: Die Lösung liegt beim Betreiber.

Nach Provider #

Aktionen #

Ein Ergebnis ist JSON mit "ok": true oder "ok": false und einem error-Text. Das Tool schlägt nie auf andere Weise fehl; ein falscher Parameter kommt als error zurück, den der Agent lesen kann.

create #

Veröffentlicht entweder einen Port oder einen Ordner, nie beides in einem Aufruf. Neu in 0.9.11 Wird derselbe Port oder Ordner in derselben Konversation erneut veröffentlicht, kommt die Preview zurück, die schon läuft, mit demselben Link und unveränderter Beschriftung; das Ergebnis sagt dann "existing": true.

Ein Dev-Server (port) #

Das Relay reicht Anfragen an einen Server durch, der auf diesem Port lauscht. Es startet diesen Server nicht, überwacht ihn nicht und startet ihn nicht neu; das bleibt ein gewöhnlicher Hintergrund-Task des Agents, mit eigenem Stopp-Button.

Jede Preview liegt unter einem eigenen Pfad auf dem Preview-Hostnamen. Der Browser fragt nach /test_<token>/…; das Relay entfernt dieses Präfix, bevor es die Anfrage weiterreicht, und teilt der App das Präfix in X-Forwarded-Prefix mit. Es schreibt keine Seiten um. Eine App funktioniert also, wenn die Links und Asset-Adressen, die sie ausgibt, relativ sind oder das Präfix tragen, während sie Anfragen ohne das Präfix beantwortet. Eine App, die /assets/app.js von der Wurzel des Hosts anfragt, findet es nicht.

Deshalb wird der Agent angewiesen, create zuerst aufzurufen und den basePath aus dem Ergebnis zu lesen, bevor er den Dev-Server startet.

{ "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."
}

Neu in 0.9.17 Der hint sagt dem Agent außerdem, den Dev-Server an 127.0.0.1 zu binden, nicht an 0.0.0.0: Der Proxy des Relays erreicht ihn dort, und sonst soll ihn nichts erreichen. Nur Sessions mit dem Tool preview bekommen diese Zeile (siehe Nach Provider). Agents, denen statt des Tools die Preview-API beigebracht wird, bekommen sie nicht: GitHub Copilot und OpenAI auf der SDK-Engine sowie Grok und die Extension-Engine von Copilot, wenn das Relay mit OAR_MCP_SERVER=0 läuft.

Ein Ordner (dir) #

Das Relay liefert die Dateien des Ordners selbst aus. Es muss nichts laufen: gut für eine Build-Ausgabe, ein Mockup, eine einzelne HTML-Datei oder einen Coverage-Bericht.

• Der Ordner muss innerhalb des Arbeitsordners der Konversation liegen. Das wird bei jeder Anfrage erneut geprüft, sodass ein Link später nicht nach außerhalb führen kann.
• Dateien und Ordner, deren Namen mit einem Punkt beginnen (.git, .env), werden nie ausgeliefert, ebenso wenig Key-Dateien (*.pem, *.key, id_rsa…).
• Für einen Ordnerpfad wird index.html ausgeliefert.
• Relative Asset-Pfade funktionieren, wie sie sind. Pfade ab der Wurzel des Hosts (/assets/app.js) nicht.
• Keine WebSocket-Verbindungen.

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

Das Ergebnis hat dieselben Felder, mit "mode": "static".

list #

Listet die Previews der eigenen Konversation des Agents auf, mit token, label, url, target (der Ordner oder localhost:<port>), online und der Konversation. Neu in 0.9.14 Vor 0.9.14 umfasste die Liste jede Preview des Relays; das Token einer Preview ist ihr einziger Schutz, deshalb sieht ein Agent jetzt nur seine eigenen. Die Liste für das ganze Relay gehört dir, unter Settings → Previews und mit /preview list. Eine Preview, die das Relay nach einem Neustart nicht prüfen konnte, trägt "unverified": true und wird nicht ausgeliefert, bis die Prüfung antwortet (siehe Nach einem Relay-Neustart).

{ "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 #

Schließt den Link. Ein Dev-Server dahinter läuft weiter.

Ohne token und mit mehreren Previews in der Konversation kommt der Aufruf mit einem error und der Liste zur Auswahl zurück.

Neu in 0.9.14 Ein Agent schließt nur die Previews seiner eigenen Konversation. Das Token der Preview einer anderen Konversation wird abgelehnt:

{ "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" } }

Grenzen #

Previews sind vom Relay getrennt: Sie werden auf einem eigenen Port unter einem eigenen Hostnamen ausgeliefert, wo es keine der eigenen Seiten oder APIs des Relays gibt. Previews teilen sich diesen Hostnamen untereinander, jede unter ihrem eigenen Pfad.