Preview and testing

This page covers the workspace’s Preview window and how to check that a page works. The Preview shows your app while you build it, and an agent on the computer controls it with rootsy preview. Check that a change works before telling anyone it does.

What the Preview window shows

The Preview window loads your computer’s address (https://<name>.rtsy.dev) inside the workspace. It shows the same app visitors get, served through the same path, so a page that works in the Preview works at the address.

People rarely refresh the Preview themselves. After you change something, refresh it for them.

Refresh the Preview after a change

rootsy preview refresh

This reloads the page the Preview is showing. It prints preview refreshed (1 viewer), with the number of open workspaces it reached.

If no workspace has this computer open, or the open one has paused after 15 minutes without input, nothing is refreshed and it prints:

no dashboard connected — the user will see the latest version when they next open it

Then tell the person which page to look at instead of saying you refreshed it.

Point the Preview at a page

To show a page you’ve built, give its path:

rootsy preview open /pricing

Paths resolve against your computer’s address. You can also pass a full https:// URL. The workspace only follows it if the host is your address or one of your active custom domains, and ignores anything else. A target must start with / or https:// and can’t be longer than 2048 characters.

Add --focus to bring the Preview window to the front:

rootsy preview open /pricing --focus

Use --focus when the person should see the result now, such as the first working version or when they asked to see it. Leave it off for routine changes so you don’t pull them away from what they’re doing. rootsy preview focus brings the Preview to the front without reloading it.

Apps with sign-ins, OAuth or browser dialogs

Embedded previews can’t hold logins. Browser privacy rules block cookies in a page framed inside another site. Sign-in, sessions and OAuth redirects fail inside the Preview even when they work at the address. After you build a sign-in, run:

rootsy preview window

The Preview then shows “Sign-ins don’t work inside an embedded preview — browsers require a real window for that.” with an “Open in its own window” button. For other features that need a real window, such as browser dialogs, use --reason other. The Preview then shows “This app needs browser features that only work in a real window.”

rootsy preview window --reason other

If no workspace is open, the command prints no dashboard connected — tell the user to use 'Open in its own window' on the Preview. Don’t say sign-in works until the person has signed in successfully in a real window.

Check that a page works

curl tells you the server answered. Several common bugs only show up in a browser. A status code can’t show you:

• a CSS rule that keeps a “hidden” element on screen. The hidden attribute loses to any display: rule you wrote, so .gate { display: grid } beats [hidden] and a login gate never hides. Use a class you control, or add [hidden] { display: none !important }.
• a stale cached response. Express sends ETags on JSON, so an API can answer 304 Not Modified and the page keeps showing old data. Turn it off with app.set("etag", false), or send Cache-Control: no-store on API routes.
• a form that posts nowhere.

To look at the page the way a visitor would, install a headless browser once, then take a screenshot:

npx --yes playwright install --with-deps chromium
ADDR=$(rootsy domains | awk '/^site:/ {print $2}')
npx --yes playwright screenshot --full-page "$ADDR/" /tmp/home.png

Then open /tmp/home.png and look at it. Claude Code can read images. When a change is visual or sits behind a login and you haven’t looked at it, say what you checked and what you didn’t.

Check the server from inside the computer

To check the full path a visitor’s request takes, request your address:

ADDR=$(rootsy domains | awk '/^site:/ {print $2}')
curl -sI "$ADDR/"

To check your nginx alone, skipping the platform in front of it, request port 8090 directly. The platform passes the visitor’s hostname in the Host header. Send it too if your config matches on server_name:

ADDR=$(rootsy domains | awk '/^site:/ {print $2}')
curl -sI -H "Host: ${ADDR#https://}" http://127.0.0.1:8090/

If port 8090 answers and the address doesn’t, see Troubleshooting.

Exit codes

rootsy preview exits 0 when the command was sent, including the no dashboard connected case where nothing was shown. It exits 1 for preview command rejected or preview control unavailable on this box, and 2 for wrong arguments. The full reference is on The rootsy command.