Skip to Content
GuidesPreview & ports

Preview & ports

Every chat runs its repository’s run script (set in the repository settings, never in your repository) and previews whatever it serves. Screenplay picks the port for each chat. The one requirement on your app: the app must listen on the port it’s given.

Most frameworks do this out of the box, because Screenplay passes the port in the standard PORT environment variable.

Every chat’s preview runs on your machine, so each one needs its own port. The run script is started under portless, which sets PORT to the port allocated to that chat:

# Next.js, Create React App, Express, Nuxt… honor $PORT already npm run dev # Vite and other tools that ignore $PORT: pass it explicitly vite --port $PORT --strictPort # A custom server node server.js --port $PORT

portless ships with the app, and Screenplay starts its proxy for you. It also gives each chat a stable URL like http://my-branch.my-app.localhost:1355 that survives preview restarts. Open in browser on a chat opens it.

If you run npx portless proxy start yourself (it asks for sudo to use port 443 and trust a local HTTPS certificate), Screenplay uses that proxy instead, and the stable URLs drop the port: https://my-branch.my-app.localhost. npx portless service install does the same and starts that proxy whenever your Mac starts.

A script that honors $PORT works on both.

When the preview never loads

On desktop, a preview that never listens on its assigned port fails with a clear error (DevServerPortIgnoredError) instead of leaving a blank frame. The usual cause is a script that ignores $PORT:

  1. Fix the Run script in the repository settings (for example add --port $PORT).
  2. Use … → Restart preview on the chat.
  3. Still stuck? The chat’s Preview terminal (under its composer) shows the preview’s and portless’s output. The chat’s agent can read the same output and restart the preview, so you can also ask it to debug the preview.

Troubleshooting lists the other ways a preview can fail.

Monorepos

A repository on a canvas previews one app. Filter your monorepo’s dev command down to that app, and pass the port as a flag:

# Turborepo turbo run dev --filter=web -- --port $PORT # pnpm workspaces pnpm --filter web dev -- --port $PORT

With Turborepo, pass the port as a flag, as above, instead of relying on the PORT variable reaching the task. Turborepo 2’s strict env mode strips undeclared variables, so $PORT is empty inside the task. Package scripts that hardcode --port 3001 also win over the variable. The appended flag handles both, because for Next.js and Vite the last --port wins. Alternatively, add "passThroughEnv": ["PORT"] to the dev task in turbo.json.

When you add a monorepo, pick the app in Configure repository and its run script is filled in for you. To work on a second app, add the repository again and pick that app; see Monorepos.

Why it works this way

  • On desktop, chats run directly on your machine, not in containers, so your already-authenticated tools (including coding CLIs on a subscription login) work inside every chat.
  • Adopting Screenplay should never require changing your code. The run script lives in Screenplay’s settings, and Screenplay invokes portless itself, so your repository needs no config files or dependencies.
Last updated on