Previews

Some changes are easier to judge by using them: a new checkout flow, a layout on a small screen, a chart with real data. An agent can start your app’s dev server inside its run and share it as a preview. You click Open preview, and the app opens in a tab of yours, served live from the agent’s sandbox while it keeps working.

Ask for one in plain words, wherever you talk to the agent:

@ryph start the dev server and send me a preview of the new checkout

An agent with a browser can click through the same dev server itself. A preview is how you get to click through it too.

Hot reload, streaming responses and WebSockets all work, so when the agent saves a change, your tab updates as it would on your own machine.

How a preview comes up

1. The agent starts the dev server

   It runs the server with ryph__background_run as a service, so the server keeps running while the agent works on, and the agent hears about it if the server stops.

2. It exposes the port

   It calls ryph__expose_port with the port and a label, such as { "port": 5173, "label": "Checkout" }. Ryph registers the preview and hands back its link, which the agent shares in the thread, the task or the pull request.

3. You open it

   Ryph checks you can see the run, then lets your browser through to the dev server. The run opened the connection from inside, so nothing in it had to be published.

4. It lives as long as the run

   When the run ends, its previews close. If the dev server crashes, the preview answers as unavailable until the agent starts it again on the same port.

Where to open it

1. Open the task in the web app.
2. In the transcript, the agent’s Exposed a preview step has an Open preview button.
3. Or switch to the run’s Commands tab. Every preview of the run is listed under Previews, with its label and port, and its own Open preview button.

Next to the list, Ryph says who can open the run’s previews: People who can see this run, or This machine only when Ryph runs on your machine.

A link the agent posts in a chat thread or a pull request works too. On a hosted deployment, opening it takes you through Ryph’s sign-in first if you need it, then the same check.

Who can open a preview

On Kubernetes with a preview domain, anyone who can see the run can open its previews, and nobody else. Each time you open one, Ryph checks you can see the run and gives your browser a one-time ticket, good for 60 seconds. The preview trades it for a cookie that works for that one preview, for up to eight hours. Networked Compose runs the same check, for a browser on the host.

On your machine and with Docker Compose, previews open at http://<id>.localhost, which only a browser on that same machine can reach. Anyone on the machine who has the link can use the app.

How Ryph contains a preview

The agent wrote the code a preview serves, and an agent can be talked into things by what it reads. So on a hosted deployment, Ryph treats every preview as a hostile page and fences it in:

• Every preview gets its own origin, <id>.<your preview domain>, with an id nobody can guess. The preview domain is separate from your Ryph app, so a page in a preview can’t read or use your Ryph session.
• The viewer cookie works for one preview only. It’s set for that exact host name, so another preview can’t read it or overwrite it. Ryph removes it from every request before it reaches the dev server.
• The page reaches what the run could. Every response carries a content security policy built from the agent’s network allowlist, which holds the page’s requests, WebSockets, scripts and forms to the hosts the run may reach.
• The dev server learns little about you. Ryph removes your IP address from every request, and drops response headers that would reach past the preview, such as Clear-Site-Data and reporting endpoints.
• Nothing outlives the run. Ryph refuses to install service workers, so a page can’t leave code running in your browser after its run ends.
• Only ports the agent registers are reachable, between 1024 and 65535, up to four per run. Ryph’s own services inside the run, such as its control API, tool server and browser, can’t be exposed.

What to keep in mind

Some things are out of Ryph’s reach once the page is in your browser:

• A page can send data out by navigating. A link it opens, a window it pops up, WebRTC and DNS prefetching all get past a content security policy. Assume anything you type into a preview can leave it.
• A page can look like anything, including your company’s sign-in. Sign in to Ryph only on your Ryph app’s address, and don’t enter a password into a preview.
• Access is checked when you open a preview. Someone who loses access to a run keeps a preview they already opened until their cookie expires, after up to eight hours, or the run ends.
• Previews can toss cookies at each other. Page code can set a cookie for the whole preview domain, which every other preview then receives. The worst it can do is confuse another preview, or fill your browser’s cookies for the domain until previews stop loading for you, which clearing them fixes. Browsers only keep subdomains apart like this for domains on the Public Suffix List, which is meant for domains that host many unrelated sites, so a preview domain will usually have this gap.
• Old Safari is looser. Safari before 16.4 lacks the request headers Ryph uses to tell a page load from an embedded script, so there one preview can load another’s scripts.

Getting your dev server ready

Most dev servers work as they are. A few settings trip them up:

• Listen on localhost inside the run. The tunnel connects to 127.0.0.1 or ::1 on the exposed port.
• Allow the preview’s host name. Dev servers that check the Host header, such as Vite with server.allowedHosts, need the preview’s domain on the list: .localhost on your machine, or your preview domain on a hosted deployment.
• Use relative URLs. An app that hardcodes localhost:5173, an OAuth callback URL or a fixed hot reload address has to be configured with the preview’s URL. The tunnel doesn’t rewrite your code.
• Call a separate API through the dev server’s proxy. Requests from one preview to another are refused, so put the API behind a same-origin proxy, such as Vite’s server.proxy.

If your app needs a database or a cache to start, give the repo an environment with those services, and the dev server finds them as it would anywhere else.

Previews on your deployment

Previews are most useful when your whole team can open them, which takes a preview domain. Today that’s possible on Kubernetes. Everywhere else, a preview is local-only: it opens only in a browser on the machine Ryph runs on.

On your machine, RYPH_LOCAL_PREVIEWS=off turns previews off. They’re also off when RYPH_APP_URL points somewhere other than localhost, since a .localhost link means nothing to a browser on another machine. The same goes for Docker Compose, where RYPH_PREVIEW_PORT moves the published port.

On Kubernetes, previews are off until you give them a domain, set up as below.

Set up a preview domain

On Kubernetes, Ryph serves previews from a dedicated domain: every preview at https://<id>.<preview domain>, open to everyone who can see its run. That domain is the boundary between code an agent wrote and everything else your people are signed in to, so choose it with care.

To set it up:

1. Register the domain and keep it for previews alone. It must not be the domain your Ryph app is on, at any level.

2. Point *.<domain> at the cluster with a wildcard DNS record and a wildcard certificate, through ingress.previews or httpRoute.previews in the Helm chart.

3. Turn previews on in the chart’s values:

   previews:
     enabled: true
     domain: acme-previews.dev

4. RYPH_PREVIEWS_TOKEN is generated by the chart. To bring your own, set it under secrets.internal, 32 random characters or more. Ryph signs preview addresses and viewer cookies with it, so anyone holding it can let themselves into any preview. Changing it gives every preview a new address and signs everyone out of open ones.

The service’s internal port, 7491, carries runs’ tunnels and Ryph’s own requests. Route only the public port, 7490, to the internet. The chart’s network policies already keep 7491 to the control plane and runs.