preview

preview を使うと、エージェントは Web UI を持つものを公開リンクに載せられます。スマートフォンから開いたり、誰かに送ったりするためです。対象は、リレーのマシンのポートで待ち受ける開発サーバーか、通常のファイルを入れたフォルダーです。自分の会話のプレビューを一覧表示したり閉じたりすることもできます。

普通の言葉で頼みます。「開発サーバーを起動してリンクをちょうだい」「ビルドしたサイトを見せて」のように。エージェントには、Web UI を見たい、試したい、共有したいときは必ずこのツールを使い、localhost を案内しないよう指示されています。

表示される内容 #

• 会話のバックグラウンドタスクのパネルにあるプレビューのカード。Open（開く）、Copy link（リンクをコピー）、Close（閉じる）があります。
• トランスクリプト内のリンクカード。エージェントがプレビューを公開した返信に付きます。プレビューがなくなると closed バッジが表示されます。会話の共有ビューではカードのラベルだけが表示され、リンクは表示されません。
• リレーのすべてのプレビュー（すべての会話にまたがるもの）は Settings → Previews（設定 → プレビュー）にあり、それぞれに閉じるためのボタンがあります。
• ポートのプレビューの背後にある開発サーバーが応答しなくなると、カードに offline バッジが表示されます。リンクは登録されたままなので、同じポートでサーバーを再び起動すれば、同じリンクがまた使えます。

エージェントを使わずに、入力欄に /preview と入力して同じことができます。

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

設定する #

プレビューは、リレーの運用者が設定するまでオフです。プレビューしているアプリがリレー自体に決して届かないよう、リレーとは別の専用のホスト名が必要です。必要なものは 3 つです。

1. 自分が管理していて、ポートだけでなく名前がリレーのものと異なるホスト名。
2. このホスト名をプレビューのポートに向けるフロントプロキシ（Caddy、Cloudflare Tunnel など）。
3. リレーの config.json の previews ブロック：

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

これを済ませていなくても、エージェントはこのツールを持っています。済ませていない場合、create の呼び出しは理由とともに返ってきます。エージェントにはその理由をあなたに伝えるよう指示されています。直すのは運用者です。

プロバイダー別 #

アクション #

結果は、"ok": true、または "ok": false と error のテキストを含む JSON です。ツールがそれ以外の形で失敗することはありません。パラメーターの誤りも、エージェントが読める error として返ってきます。

create #

ポートかフォルダーのどちらかを公開します。1 回の呼び出しで両方を公開することはありません。 0.9.11 で追加 同じ会話で同じポートやフォルダーをもう一度公開すると、すでに公開中のプレビューが、同じリンクと変わらないラベルで返されます。このとき結果には "existing": true が含まれます。

開発サーバー（port） #

リレーは、そのポートで待ち受けるサーバーにリクエストを中継します。そのサーバーの起動、監視、再起動は行いません。サーバーは、専用の停止ボタンを持つ、エージェントの通常のバックグラウンドタスクのままです。

各プレビューは、プレビューのホスト名の下にある専用のパスに置かれます。ブラウザーは /test_<token>/… を要求します。リレーはリクエストを中継する前にこのプレフィックスを取り除き、X-Forwarded-Prefix でアプリにプレフィックスを伝えます。ページの書き換えは行いません。そのため、アプリが動くのは、送り出すリンクやアセットのアドレスが相対パスかプレフィックス付きで、かつプレフィックスなしのリクエストに応答する場合です。ホストのルートから /assets/app.js を要求するアプリは、それを見つけられません。

そのため、エージェントには、開発サーバーを起動する前に最初に create を呼び出し、結果から basePath を読むよう指示されています。

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

0.9.17 で追加 hint は、開発サーバーを 0.0.0.0 ではなく 127.0.0.1 にバインドするようにもエージェントに伝えます。リレーのプロキシはそこで開発サーバーに届き、それ以外のものが届くべきではないからです。この 1 行を受け取るのは、preview ツールを持つセッションだけです（プロバイダー別を参照）。ツールの代わりにプレビュー API を教わるエージェントは受け取りません。SDK エンジンの GitHub Copilot と OpenAI、そしてリレーが OAR_MCP_SERVER=0 で動いているときの Grok と Copilot の拡張機能エンジンです。

フォルダー（dir） #

リレー自身がフォルダーのファイルを配信します。何も動かす必要がないので、ビルドの出力、モックアップ、単一の HTML ファイル、カバレッジレポートに向いています。

• フォルダーは会話の作業フォルダーの中になければなりません。これはリクエストのたびに改めて確認されるので、後からリンクの行き先を外に向けることはできません。
• 名前がドットで始まるファイルとフォルダー（.git、.env）は決して配信されません。鍵ファイル（*.pem、*.key、id_rsa…）も同様です。
• フォルダーのパスには index.html が配信されます。
• 相対パスのアセットはそのまま動きます。ホストのルートからのパス（/assets/app.js）は動きません。
• WebSocket 接続はできません。

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

結果のフィールドは同じで、"mode": "static" になります。

list #

エージェント自身の会話のプレビューを、token、label、url、target（フォルダー、または localhost:<port>）、online、会話とともに一覧表示します。0.9.14 で追加 0.9.14 より前は、一覧にはリレーのすべてのプレビューが含まれていました。プレビューのトークンが唯一の保護なので、現在エージェントに見えるのは自分のプレビューだけです。リレー全体の一覧は、Settings → Previews と /preview list であなたが見られます。再起動後にリレーが確認できなかったプレビューには "unverified": true が付き、確認の応答があるまで配信されません（リレーの再起動後を参照）。

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

リンクを閉じます。背後にある開発サーバーは動き続けます。

token を指定せず、会話にプレビューが複数ある場合、呼び出しは error と、選ぶための一覧とともに返ってきます。

0.9.14 で追加 エージェントが閉じられるのは、自分の会話のプレビューだけです。別の会話のプレビューのトークンは拒否されます。

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

制限 #

プレビューはリレーから切り離されています。別のポートで、別のホスト名の下で配信され、そこにはリレー自身のページも API も存在しません。プレビュー同士はそのホスト名を共有し、それぞれが専用のパスの下にあります。