Previews

A preview URL routes browser traffic to a web process running inside the sandbox. The sandbox must be ready and the process must listen on a configured port.

Find the preview URL

Readiness identifies the template's selected preview URL:

const ready = await sandbox.ready();

console.log(ready.data.previewUrl);

Use sandbox.runtime.ports.list() when the sandbox exposes more than one HTTP service. Port information describes running services; it does not start a web server.

Protect a preview

Set or replace the preview password through the management API:

await sandbox.preview.setPassword({
  password: process.env.PREVIEW_PASSWORD!,
});

Do not log the password or store it in sandbox source files. Call sandbox.preview.disable() only when removing protection is intentional.

Create a temporary session

A preview session produces a time-limited URL that bootstraps browser access without sharing the password:

const ready = await sandbox.ready();
const session = await sandbox.preview.createSession({
  url: ready.data.previewUrl,
});

console.log(session.url, session.expiresAt);

Preview protection must already be enabled. Treat the returned URL and token as credentials: pass them only to the intended consumer and do not place them in public logs.

Hand off application state

A handoff creates an isolated preview session and transfers the source session's cookie state when the recipient opens it. This lets a reviewer continue from an authenticated or prepared product state without receiving the original session.

const handoff = await sandbox.preview.createHandoff({
  previewSessionId: session.previewSessionId,
  expiresInSeconds: 900,
  url: ready.data.previewUrl,
});

console.log(handoff.url);

A handoff is single-use and short-lived. Create one for each recipient rather than reusing a session URL.

See Previews and sharing for the product model and Publish a sandbox when the product needs a deployment rather than a live sandbox URL.