---
title: "Embedded previews"
description: "Relay live previews through your own authenticated HTTP and WebSocket gateway."
canonical_url: "https://hoplite.sh/docs/platform/previews"
markdown_url: "https://hoplite.sh/docs/platform/previews.md"
---

# Embedded previews
URL: /docs/platform/previews
LLM index: /llms.txt
Description: Relay live previews through your own authenticated HTTP and WebSocket gateway.

# Embedded previews

Your dashboard embeds your gateway. Your gateway authenticates the customer and relays requests to Hoplite. Hoplite routes them to the sandbox and restores saved source when a runtime has expired.

```text
dashboard iframe → your authenticated gateway → Hoplite preview proxy → sandbox
```

## Start a preview

Call `POST /api/platform/v1/projects/{projectId}/threads/{threadId}/preview/start` from your backend with `{"frameOrigin":"https://dashboard.example.com"}`. Use an exact HTTPS origin, with no path or trailing slash. Starting requires `thread:update`; the thread must already have a provisioned workspace. Configure its run command and preview port through the Projects API, or use application detection.

The response contains `preview.status`, `preview.url`, and a `preview.gateway` credential when available. A starting preview may have no URL yet. Read `GET /api/platform/v1/projects/{projectId}/threads/{threadId}/preview?frameOrigin=...` to inspect readiness and refresh access.

## Relay requests

Use a long-lived service that supports WebSocket upgrades. The runnable gateway in `examples/borradh-studio/apps/studio/server.ts` demonstrates transport and token renewal; its loopback authentication is for the local demo.

For each HTTP request and WebSocket upgrade:

1. Authenticate your user and verify membership in the organization that owns the site.
2. Resolve its Hoplite thread from your server-side mapping. Never accept an arbitrary upstream URL from the browser.
3. Forward the request to `preview.url`, adding the returned gateway token as `X-Hoplite-Preview-Token`. Strip any browser-supplied version of that header.
4. Preserve the request path, query, WebSocket protocols, and response content. Rewrite redirects and cookie domains where required. For upgrades, use the Hoplite preview origin as the upstream `Origin`.

Give each preview an isolated origin so root-relative assets and HMR resolve correctly. Keep service keys, gateway tokens, and upstream URLs on the server. Hoplite strips its access header before forwarding to generated code, restricts framing to your dashboard origin, and disables indexing and caching.

## Renew access and record activity

Gateway credentials last five minutes. Refresh them through GET; an idempotent start replay returns the original credential, which may have expired. Open WebSockets close within five seconds of the next authorization check after expiry, so reconnect with refreshed access.

Revoking a service key prevents new grants but does not revoke an existing grant before expiry. Your gateway must immediately reject users whose membership is removed.

Preview polling does not count as editor activity. Call the [workspace activity endpoint](/docs/api/recordPlatformWorkspaceActivity) while a user is actively editing to renew the sandbox idle deadline. Starting a preview does not publish a release or perform release QA.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).