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://{port}-{slug}.sandbox.miosa.ai where {slug} is the first 8 characters of the sandbox UUID. For the template default port, the URL is https://{slug}.sandbox.miosa.ai (no port prefix). For white-label platforms, this can be https://{port}-{slug}.sandbox.{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://3000-abc12345.sandbox.miosa.ai?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://3000-abc12345.sandbox.miosa.ai?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 *.sandbox.miosa.ai, *.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 goes to expired on token TTL elapses; expired goes to deleted on delete.

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.

Use case	Recommended TTL
Interactive work session	3 600 s (1 hour) - refresh when the user returns
Short demo or share link	900 s (15 minutes)
Public share with explicit expiry	Up to 86 400 s (24 hours)
Permanent share	No TTL - use `sandbox.share.create()` with no expiry, manage revocation manually

When a token expires, the iframe shows a “session expired” message from the preview proxy. Your UI should catch the message event from the iframe and re-mint a token transparently.

Iframe sandbox flags

<iframe
  src="https://preview.example.com/p/sbx_abc123?preview_token=miosa_pv_..."
  allow="clipboard-read; clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
  style="width: 100%; height: 600px; border: none;"
  title="Design workspace"
></iframe>

Flag	Required?	Reason
`allow-scripts`	Yes	Preview content runs JavaScript.
`allow-same-origin`	Yes	Lets the preview proxy set session cookies.
`allow-forms`	Recommended	Many sandbox apps submit forms.
`allow-popups`	Optional	Only if your sandbox app opens new windows.
`allow-downloads`	Optional	Only if your sandbox app serves file downloads.

Do not add allow-top-navigation - it would let sandbox content redirect your top-level page.

Token refresh

Detect expiry by listening for the message event from the iframe:

window.addEventListener("message", async (event) => {
  // The preview proxy emits this message when the token expires.
  if (event.data?.type === "miosa:preview:expired") {
    const res = await fetch(`/api/embed-url?sandbox_id=${sandboxId}`);
    const { embed_url } = await res.json();
    document.getElementById("sandbox-frame").src = embed_url;
  }
});

Permission scoping

When you mint a token for an end user, scope it to the minimum permissions they need:

Available permission scopes:

Scope	Grants
`sandbox:read`	Read sandbox metadata and state
`sandbox:exec`	Run commands inside the sandbox
`preview:read`	Embed and view previews
`preview:share`	Create public share links
`files:read`	Read the sandbox filesystem
`files:write`	Write files to the sandbox

Early revocation

Revoke a preview token before it expires - for example, when a user logs out or loses access: