# 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:

```ts
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:

```ts
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:

```ts
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.

```ts
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](/docs/concepts/previews) for the product model and [Publish a sandbox](/docs/publishing) when the product needs a deployment rather than a live sandbox URL.