Skip to Content

Preview exposure

Desktop

When Screenplay runs on a machine you control, every chat’s preview runs there too, and a browser has to reach it. Preview exposure decides how. It’s a small interface in apps/app/lib/preview-exposure/ with two built-ins:

Built-inPreviews bindA browser loadsFor
loopback127.0.0.1http://localhost:{port}Everywhere else
tailscale127.0.0.1https://<mac>.<tailnet>.ts.net:{port}The Mac app’s Sharing

In the Mac app, it’s how viewers reach the app and its previews, and only while Sharing is on: the viewer listener is exposed when Sharing turns on, and a viewer’s frame asks for its port’s origin when it opens. Turning Sharing off releases every port it exposed. Your own frames always load at http://localhost:{port}.

Headless doesn’t use it: the host’s frames load through portless at http://screenplay-<port>.localhost:1355, over the host’s SSH tunnel.

It covers only what a browser loads: each chat’s bridge proxy (the page a frame shows) and its frame stream. The preview itself always listens on 127.0.0.1. The server never loads a browser URL either: its own checks, thumbnails and the agent’s page reads go to each preview’s 127.0.0.1 address, so they work whatever URL your browser uses. Hosted sandboxes don’t use it; each Vercel Sandbox has its own public URL.

The interface

interface PreviewExposure { // Make a port reachable, once its listener is started. Idempotent. expose(port: number): Promise<{ browserOrigin: string }> // Undo expose when the chat is deleted. Never throws. release(port: number): Promise<void> }

Built-ins

loopback: loopbackExposure()

Each port loads at http://localhost:{port}. The default everywhere but the Mac app.

tailscale: tailscaleExposure()

Shares each port with everyone on your tailnet. Exposing a port runs tailscale serve --bg --https=<port> http://127.0.0.1:<port>, and the port loads at https://<mac>.<tailnet>.ts.net:<port>; releasing it runs tailscale serve --https=<port> off. --bg keeps each port served after a restart until it’s released.

It needs Tailscale installed, signed in and connected, with MagicDNS and HTTPS Certificates turned on for your tailnet (the DNS page of the Tailscale admin console). When any of those is missing, the preview shows an error saying which.

OptionDefault
clitailscale, then /Applications/Tailscale.app/Contents/MacOS/TailscaleThe commands to try, in order

Picking one

selectPreviewExposure() in apps/app/lib/preview-exposure/index.ts picks one: tailscale in the Mac app, loopback everywhere else. PREVIEW_EXPOSURE overrides it with loopback or tailscale. An id it doesn’t know stops the server from starting.

Every replaceable part of Screenplay is picked the same way, like the Yjs host.

Last updated on