Previews

A Preview is a URL that routes to a port inside a running Sandbox. The agent writes code, starts a dev server, the preview updates live in the browser. This is the build loop of AI app builders.

Quick create

The URL follows the pattern https://<preview_slug>.preview.miosa.app. For white-label platforms, this can be https://<preview_slug>.preview.<your-domain> once DNS delegation is set up.

Visibility

Mode	Access
`public`	Anyone with the URL can view (and is rate-limited by IP). No auth required.
`private`	Requires either an authenticated MIOSA session OR a valid share token.

For most white-label use cases, always use private. Then mint a share token to hand to the end user’s browser.

A share token is a short-lived, scoped credential that lets a specific browser access a private preview without exposing your MIOSA workspace API key.

Response:

{
  "data": {
    "id": "preview_...",
    "share_token_prefix": "first12chars",
    "share_token_expires_at": "2026-05-14T19:30:00Z"
  },
  "preview_token": "miosa_pv_<one-time-raw-token>",
  "share_url": "https://abc12345.preview.miosa.app?preview_token=miosa_pv_<one-time-raw-token>"
}

The token can be passed two ways:

As ?preview_token=... query string in the URL (most common; works for iframes).
As x-miosa-preview-token: <token> HTTP header (when you control the request).

MIOSA’s proxy strips the credential before forwarding to your sandbox app — your app never sees the token. The proxy authenticates the request, then forwards a clean HTTP request to your dev server on the sandbox.

Iframe embedding

Previews are designed to be embedded in iframes:

<iframe src="https://abc12345.preview.miosa.app?preview_token=miosa_pv_..."
        sandbox="allow-same-origin allow-scripts allow-forms"
        style="width:100%; height:600px; border:0;"></iframe>

The preview proxy emits CSP frame-ancestors for *.miosa.app, *.miosa.ai, and localhost:4000 by default. For white-label embedding into your own domain, contact support — the production proxy CSP is configurable per tenant.

How it works

Lifecycle


active → expired → deleted

active while the underlying sandbox is running and the preview hasn’t been explicitly deleted.
expired once the share token TTL (if set) elapses.
deleted when you delete it, or automatically a short time after the sandbox is destroyed.

Re-creating a preview on the same port returns a new preview record with a new slug. Old preview URLs do not automatically transfer.

Preview vs Deployment URL

	Preview	Deployment URL
What it points at	A live sandbox port	An immutable deployment version
Updates live?	Yes — sandbox edits reflect immediately	No — only changes on rollback / re-promote
Lifetime	Tied to the sandbox	Persistent
Use it for	Build loop, sharing in-progress work	Production traffic

You don’t promote a preview to a deployment. You publish from a sandbox (which produces a deployment version with its own URL). The preview keeps living until the sandbox dies.

Abuse limits

Public previews are aggressively rate-limited by IP at the edge. Private previews are rate-limited per share token. If you’re embedding into a high-traffic site, use a custom domain and a dedicated tenant plan — preview hosts are not designed to serve production traffic.