プレビュー

プレビューは、Web UI を持つものを公開リンクに載せます。リレーのマシンのポートで待ち受ける開発サーバーか、通常のファイルを入れたフォルダーです。リンクはどのデバイスからでも開け、誰にでも送れます。リレーは公開されません。プレビューは、別のホスト名にある別のリスナーから配信されます。

よくある使い方：

• スマートフォンでアプリを開く：エージェントが開発サーバーを起動し、あなたはリンクをタップして実機でレイアウトを試します。
• 誰かにリンクを送る：同僚は、あなたのマシンやリレーにアクセスしなくても、モックアップやビルドしたサイトを開けます。
• Webhook を開発サーバーに向ける：公開アドレスを必要とするサービスから、作成中のアプリを呼び出せます。

このページは、オーナーと運用者向けのガイドです。エージェントのツールについては、パラメーター、結果、制限を含めて preview で説明しています。

プレビューをリレーから切り離す仕組み #

プレビューは、専用のポートで動く 2 つ目の HTTP リスナーから配信され、専用のホスト名で公開されます。ここから 2 つのことが言えます。

• リレーはそのポートにありません：リレーの API、Web アプリ、ライブ接続、共有リンクは、そこにはマウントされていません。そのリスナー上に存在しないので、プレビューのトラフィックはそれらに届きません。プレビューの作成や終了にはリレーのアクセストークンが必要で、リレー自身のポートでのみ行われます。
• ホスト名が異なります：プレビューしているアプリは、リレーとは別のブラウザーのオリジンで動きます。その JavaScript は、リレーのサインイン用 Cookie を送れず、リレーの Web アプリのストレージも読めません。

ポートだけでなく、ホスト名が異なる必要があります。Cookie はポートを区別しないので、relay.example.com:3334 は relay.example.com のサインイン用 Cookie を共有してしまいます。ホスト名が同じ場合、リレーはレーンの起動を拒否します。

さらに、レーンは、リレーのサインイン用 Cookie（copilot_auth）や、リレーのアクセストークンを含む Authorization ヘッダーを、プレビューしているアプリに決して転送しません。手動で作成したリクエストにそれらが含まれていても同じです。アプリ自身の Authorization ヘッダーはそのまま通ります。

なお、プレビュー同士は 1 つのホスト名を共有し、それぞれが専用のパスの下にあります。注意点を参照してください。

設定する #

プレビューは、運用者が設定するまでオフです。手順は 3 つです。

1. ホスト名 #

自分が管理していて、名前がリレーのものと異なるホスト名を選びます。例：relay.example.com に対する preview.example.com。その DNS をフロントプロキシかトンネルに向けます。プレビューはサブドメインではなくパスで区別されるので、すでに持っているゾーンの下に 1 階層のホスト名が 1 つあれば十分です。Cloudflare では、その名前は Universal 証明書の対象になります。*.preview.example.com のような 2 階層のワイルドカードは対象にならないため、プレビューごとのサブドメインはありません。

2. フロントプロキシ #

プロキシは、プレビューのホスト名をプレビューのリスナーに送ります。リスナーのポートの既定値は、リレーのポートに 1 を足したものです（リレーが 3333 なら 3334）。previews.port で固定したポートを使ってください。プロキシには安定した転送先が必要です。

Caddy

preview.example.com {
    reverse_proxy 127.0.0.1:3334
}

Cloudflare Tunnel

すでに使っているトンネルに、2 つ目の公開ホスト名を追加します。追加する場所は、Cloudflare のダッシュボードの Public Hostnames → Add（パブリックホスト名 → 追加）、またはトンネルの config.yml です。

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. previews ブロック #

リレーの config.json にこのブロックを追加し、リレーを再起動します（oar restart を参照）。

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

すべてのキー、既定値、例外的なケースは、config.json の表にあります。

環境変数による上書き #

COPILOT_PREVIEWS_ENABLED、COPILOT_PREVIEWS_PORT、COPILOT_PREVIEWS_BIND_HOST、COPILOT_PREVIEWS_PUBLIC_BASE_URL、COPILOT_PREVIEWS_ALLOWED_TARGET_HOSTS は、対応するキーを上書きします。値と、どれが何より優先されるかは、環境変数にあります。

レーンが起動を拒否するとき #

設定を誤ったレーンが、リレーを止めることはありません。リレーは動き続け、レーンはオフのままです。どの確認も、上で説明した分離を守るためのものなので、警告に格下げされることはありません。

理由は 2 か所で確認できます。

• リレーのログ（起動時）：確認に失敗するごとに、PREVIEW LANE disabled: <message> という行が 1 行出ます。確認に通ると、ログには [preview] listener on http://127.0.0.1:3334 → https://preview.example.com と出ます。ログの場所はファイルとフォルダーにあります。
• 公開リクエストへの応答：API は 503 で Preview lane failed its startup checks を返し、メッセージは details に入ります。エージェントの preview ツールはこれを伝え、エージェントはそれをあなたに伝えるよう指示されています。previews.enabled が設定されていないときの応答は Preview lane is disabled (set previews.enabled and previews.publicBaseUrl) で、ログには行が出ません。

Settings → Previews（設定 → プレビュー）と /preview の通知には、理由は表示されません。設定タブには存在するプレビューが一覧表示され、通知は公開に失敗したことだけを伝えます（/preview を参照）。リレーのログを確認してください。

ポートがほかのプログラムに使われている場合、確認は通りますが、リスナーはバインドできません。そのとき、ログには PREVIEW LANE failed to bind :<port> — <reason> と出ます。API から見るとレーンは動いていますが、プレビューのポートでは何も応答しないため、リンクは開きません。ポートを空けるか、別の previews.port を設定してください。

公開する 3 つの方法 #

エージェントに頼む #

望むことを伝えます。たとえば「開発サーバーを起動してリンクをください」「ビルドしたサイトを見せて」です。エージェントは preview ツールを使います。ツールのないプロバイダーでは、リレーのプレビュー API を使います。エージェントは、リンクと、そのリンクが公開されていることを伝えます。どのプロバイダーにツールがあるかは、リファレンスページの表にあります。

入力欄の /preview #

このコマンドは、ブラウザーからリレーに対して実行されます。どのプロバイダーでも使え、エージェントのターンを消費しません。メッセージに何も添付されていないときに実行されます。通知は会話の中に表示されます。

数字だけでできた最初の語は常にポートとして扱われ、1〜65535 の範囲外のポートでは使い方の行が表示されます。8080 という名前のフォルダーには、./8080 と入力します。

公開に失敗したとき、通知は原因（誤ったポート、作業フォルダーの外にあるフォルダー、満杯のレーン、無効なレーン）にかかわらず同じです。

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

正確な理由は表示されません。一覧は Settings → Previews の見出し Live previews（ライブプレビュー）の下にあります。理由を確認するには、API（下記）を呼び出すか、トラブルシューティングの表を見てください。リレーに到達できない場合、通知は Preview command failed — could not reach the relay. です。コマンドメニューとそのキーは、入力欄にあります。

API #

上記はすべて、リレーのポートにある同じ API を使います。この API には、リレーのアクセストークン（config.json の authToken。サインインに使うのと同じトークン）をベアラートークンとして渡す必要があります。先に登録してベースパスを確認し、その下で開発サーバーを起動します。

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 は、その会話に同じポートまたはフォルダーのライブのプレビューがすでにあり、それが返されたときに true になります。

プレビューのパスの下でアプリを動かす #

すべてのプレビューは、共有のプレビュー用ホスト名の /test_<token>/ の下にあります。プロキシの動作から、次のルールが導かれます。

• ブラウザーは /test_<token>/… を要求します。
• アプリは、そのプレフィックスなしのパスを受け取ります。
• そのためアプリは、ページ内のリンクとアセットの URL を、プレフィックス付きか相対のどちらかにする必要があり、かつプレフィックスのないリクエストにも応答しなければなりません。

プロキシが途中で行うこと：

ページ、スタイルシート、スクリプトの本文は書き換えません。HTML に /assets/app.js と書くアプリは、プレビュー用ホスト名のルートに要求を送りますが、そこにはプレビューがないため、ブラウザーには No such preview のページ（404）が返ります。これは、アプリが自分のプレフィックスを知らないことを示しています。

動作するもの #

• 相対 URL：ページで ./assets/app.js 形式のアドレスを使うアプリは、そのまま動作します。ページは /test_<token>/ にあるので、アドレスはプレビューの中で解決されます。これはプロキシの仕組みから導かれることで、フレームワークごとに試したわけではありません。
• プレフィックスを読み取る：プレフィックスなしのパスでルーティングし、X-Forwarded-Prefix からリンクを組み立てるアプリは、ルールにぴったり合います。
• ビルドしたサイト：相対、またはプレフィックスと同じベースでビルドし、出力フォルダーを静的プレビューとして公開します。/test_<token>/assets/… へのリクエストはフォルダーから配信されるので、どちらの種類の URL も動作します。

そのままでは動作しないもの #

プレフィックス付きのリクエストだけにアプリを応答させるツールの設定は合いません。プロキシがプレフィックスを取り除くためです。

• base をプレフィックスにした（--base）Vite 開発サーバー：リレーのマシン上の Vite 8.3.1 のソースで確認しました。開発サーバーは、base で始まるパスしか扱いません。/ へのリクエストには base へのリダイレクトで応答し、プロキシはそれをそのままにするので、ブラウザーはループします。その他のプレフィックスなしのリクエストには、サーバーに公開ベース URL があることを示す 404 が返ります。ホットリロードは base の下のパスでしか待ち受けず、プレフィックスを取り除いたリクエストはそれに一致しません。ビルドしたサイトの方法を使うか、ルートから相対 URL で配信する Vite の構成を使ってください。
• ルーターをプレフィックスにマウントした Express（app.use(prefix, router)）：アプリが受け取るのは /test_<token>/x ではなく /x なので、マウントが一致しません。ルーターを / にマウントし、X-Forwarded-Prefix からリンクを組み立ててください。

Next.js（basePath、assetPrefix）と SvelteKit（kit.paths.base）は、OAR のエージェント向けのメモで言及されています。ただし、そのメモはプロキシの動作と照らし合わせて確認されておらず、どちらのツールもここではテストに使えません。ベースの設定によってアプリがすべてのリクエストにプレフィックスを期待するようになるなら、Vite と同じ理由で合いません。未検証です。頼る前に試してください。

静的プレビュー #

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

• フォルダーは会話の作業フォルダーを基準に決まり（絶対パス、またはそこからの相対パス）、その中になければなりません。会話なしで公開したプレビューは、リレー自身の作業フォルダーを使います。これは公開時とリクエストのたびに確認されるので、後から作ったシンボリックリンクで外に出ることはできません。
• フォルダーのパスには index.html が返されます。キャッシュはされません。
• 決して配信されないもの：名前がドットで始まるファイルとフォルダー（.git、.env）と、鍵ファイル（*.pem、*.key、id_rsa、id_ed25519、id_ecdsa、id_dsa で始まる名前）。
• 相対のアセットパスは動作します。プレビューのプレフィックスで始まるものも動作します。ルートからの絶対パス（/assets/app.js）は動作しません。
• index.html のないフォルダーと、存在しないファイルには、Not found のページ（404）が返ります。
• 静的プレビューは常に online で、WebSocket 接続を拒否します。

プレビューの管理 #

• バックグラウンドタスクパネルのカード：会話の各プレビューにはカードがあります。カードには、ラベル、ポート、リンクが公開されていることを示す注意書き、リレーが確認した後の online または offline のバッジ、ボタン Open（開く）、Copy link（リンクをコピー）、Close（閉じる）が表示されます。パネルについては、バックグラウンドタスクで説明しています。
• トランスクリプトのリンクカード：会話のターンの実行中にプレビューが公開されると、エージェントが公開した場合も、あなたが /preview で公開した場合も、返信にリンクカードが付きます。ターンとターンの間に公開したプレビューには、トランスクリプトのカードはありません。プレビューがなくなると、カードには closed のバッジが表示され、リンクは表示されなくなります。共有された会話では、カードはラベルだけが表示され、本文中に引用されたプレビューのリンクはすべて [preview link removed] と表示されます。
• Settings → Previews：一覧 Live previews には、すべての会話から、リレーのすべてのプレビューが表示されます。会話 ID の最初の 8 文字と、0.9.11 で追加 公開した日時と最後に開いた日時も表示されます。その会話を離れた後は、ここで閉じてください。Settings（設定）を参照してください。

offline と closed は別物です。リレーは、ポートのプレビューすべてを 15 秒ごとに、ポートへの接続を試みて確認します（公開したときにも、すぐに 1 回確認します）。何も応答しないと、カードには offline のバッジと「offline — dev server not responding」という注意書きが表示されます。リンクは有効なままです。同じポートでサーバーを再び起動すれば、同じリンクが動作します。closed は、プレビューがなくなり、リンクがもう解決されないことを意味します。

プレビューを閉じても、終わるのはリンクだけです。開発サーバーは、バックグラウンドタスクとしてそのまま動き続けます。

プレビューは、自動では期限切れになりません。閉じたとき、または 0.9.11 で追加 その会話を削除したとき（リレーのキャッシュの再構築による削除も含む）に終わります。会話をアーカイブしても、そのプレビューはライブのまま Settings → Previews に残ります。

同じ会話で同じポートやフォルダーを再び公開すると、新しいプレビューではなく、すでにライブのプレビューが同じリンクで、ラベルも変えずに返されます。

同時にライブにできるプレビューは、リレー全体で最大 8 件です（previews.maxLive）。拒否のメッセージには、最も古い 3 件が、それぞれ公開した日時と最後に開いた日時、閉じ方とともに示されます。

リレーの再起動後 0.9.11 で追加 #

プレビューは、リレーの再起動、更新、クラッシュの後も残ります。リレーはプレビューをデータベースに保持し、起動時に復元するので、渡したリンクは動作し続けます。ただし、それぞれ先に再確認され、もう有効でないと判断されたものは終わります。

• フォルダーのプレビューで、フォルダーがなくなったか、会話の作業フォルダーの中にもうないもの
• マシンの再起動後のポートのプレビュー：開発サーバーはなくなっており、そのポートは後で別のものが使っている可能性があります
• 会話がもう存在しないプレビュー

Linux と macOS は、再起動を確実に報告します。Windows では、Restart（再起動）は再起動として数えられます。しかし fast startup（高速スタートアップ）がオン（Windows の既定）の状態で Shut down（シャットダウン）してから電源を入れた場合は、数えられません。その場合、以前のポートのプレビューが戻り、その時点でそのポートで待ち受けているものに到達します。不要になったプレビューは閉じてください。

確認が答えを出せない場合（データベースがビジー、またはフォルダーがなくなった以外の理由で読めない）、プレビューは終わりません。その間は配信されません。Settings → Previews とツールの list では配信されていない状態（unverified）として表示され、上限の数に含まれ、閉じることもできます。リレーは 15 秒ごとに再確認し、確認が答えを出したらすぐに、同じリンクで再び配信します。その会話で同じポートやフォルダーを再び公開すると、すぐにそうなります。10 分間答えが出ないと、プレビューは終わり、ログにその旨が記録されます。

ポートのプレビューは起動直後にも 1 回確認されるので、online や offline のバッジは最新の状態です。リレーのログでは、プレビューはトークンではなく、短いハッシュで示されます。再起動で保持されるもの、失われるものも参照してください。

WebSocket #

ポートのプレビューは、WebSocket 接続を同じプレフィックスの下で通します。プレフィックスは通常のリクエストと同様に取り除かれるので、ブラウザーがプレビューのリンクを通じて接続すれば、アプリ自身のソケットは動作します。（ホットリロードはアプリ側の問題です。上の Vite の項を参照してください。）静的プレビューと、不明または閉じたリンクは、WebSocket のリクエストに 404 で応答します。アプリがアップグレードに通常の応答を返すと、ブラウザーはそのステータスを受け取ります。アプリが停止していれば 502 です。

注意点 #

• プレビュー同士はオリジンを共有します：Cookie は各プレビューのパスに限定され、トークンは推測できません。しかし 2 つのプレビュー同士は、それぞれとリレーほどには分離されていません。
• 既定では自分のマシンだけ：ポートのプレビューの転送先にできるのは、ループバックアドレスと previews.allowedTargetHosts のホストだけです。リレー自身のポートは常に拒否されます。それを公開すると、リレーのサインインページが公開ホスト名に載ってしまうからです。
• リレーはアプリを動かしません：開発サーバーを起動したり再起動したりすることはありません。サーバーが止まると、カードは offline になります。

プロバイダー別 #

プレビューは、どのプロバイダーでも同じように見えます。違うのはエージェントが公開する方法だけで、リファレンスページに示されています。/preview と Settings → Previews は、すべてのプロバイダーで使えます。

トラブルシューティング #