preview

With preview an agent puts something with a web UI on a public link, so you can open it from your phone or send it to someone: a dev server that listens on a port of the relay's machine, or a folder of plain files. It can also list and close the previews of its own conversation.

Ask in plain words: "start the dev server and give me a link", "show me the built site". The agent is told to use the tool whenever you want to see, try or share a web UI, and never to send you to localhost.

What you see #

• A card for the preview in the conversation's background-task panel, with Open, Copy link and Close.
• A link card in the transcript, on the reply in which the agent published it. It shows a closed badge once the preview is gone. A shared view of the conversation shows the card's label only, never the link.
• Every preview of the relay, across all conversations, under Settings → Previews, each with a button to close it.
• An offline badge on the card when the dev server behind a port preview stops answering. The link stays registered: start the server again on the same port and the same link works again.

You can do the same without an agent by typing /preview in the composer:

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

Setting it up #

Previews are off until the relay's operator sets them up. They need a hostname of their own, separate from the relay's, so that a previewed app can never reach the relay itself. Three things:

1. A hostname you control that differs from the relay's by name, not only by port.
2. A front proxy (Caddy, a Cloudflare Tunnel, …) that points this hostname at the preview port.
3. A previews block in the relay's config.json:

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

Agents have the tool whether or not this is done. Without it, a create call comes back with the reason, and the agent is told to pass that on to you: it is the operator's fix.

By provider #

Actions #

A result is JSON with "ok": true, or "ok": false and an error text. The tool never fails in another way; a wrong parameter comes back as an error the agent can read.

create #

Publishes either a port or a folder, never both in one call. Added in 0.9.11 Publishing the same port or folder again in the same conversation returns the preview that is already live, with the same link and the label unchanged; the result then says "existing": true.

A dev server (port) #

The relay passes requests through to a server that listens on that port. It does not start, watch or restart that server; that stays an ordinary background task of the agent, with its own stop button.

Every preview lives under its own path on the preview hostname. The browser asks for /test_<token>/…; the relay removes that prefix before it passes the request on, and tells the app the prefix in X-Forwarded-Prefix. It does not rewrite pages. So an app works when the links and asset addresses it sends out are relative or carry the prefix, while it answers requests without the prefix. An app that asks for /assets/app.js from the root of the host will not find it.

That is why the agent is told to call create first and read the basePath from the result before it starts the dev server.

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

Added in 0.9.17 The hint also tells the agent to 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. Only sessions with the preview tool get this line (see By provider). Agents that are taught the preview API instead of the tool do not: GitHub Copilot and OpenAI on the SDK engine, and Grok and Copilot's extension engine when the relay runs with OAR_MCP_SERVER=0.

A folder (dir) #

The relay serves the folder's files itself. Nothing has to run: good for a build output, a mockup, a single HTML file or a coverage report.

• The folder must be inside the conversation's working folder. This is checked again on every request, so a link cannot be made to lead outside later.
• Files and folders whose names start with a dot (.git, .env) are never served, and neither are key files (*.pem, *.key, id_rsa…).
• index.html is served for a folder path.
• Relative asset paths work as they are. Paths from the root of the host (/assets/app.js) do not.
• No WebSocket connections.

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

The result has the same fields, with "mode": "static".

list #

Lists the previews of the agent's own conversation, with token, label, url, target (the folder, or localhost:<port>), online and the conversation. Added in 0.9.14 Before 0.9.14 the list covered every preview of the relay; a preview's token is its only protection, so an agent now sees only its own. The relay-wide list is yours, in Settings → Previews and with /preview list. A preview the relay could not check after a restart carries "unverified": true and is not served until the check answers (see After a relay restart).

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

Closes the link. A dev server behind it keeps running.

With no token and several previews in the conversation, the call comes back with an error and the list to choose from.

Added in 0.9.14 An agent closes only its own conversation's previews. The token of another conversation's preview is refused:

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

Limits #

Previews are kept apart from the relay: they are served on a separate port under a separate hostname, where none of the relay's own pages or API exist. Previews share that hostname with each other, each under its own path.