Preview URLs
A URL onto a port inside a sandbox, with a credential that can be rotated.
Use the port_expose sandbox tool or previews.mint to obtain a URL for a running
application in a sandbox. Use the returned signedUrl; do not construct the URL from
a sandbox ID or port.
curl https://app.trycereal.ai/v1/previews/mint \
-H "Authorization: Bearer $CEREAL_API_KEY" -H "Content-Type: application/json" \
-d '{ "sessionId": "ses_…", "port": 5173,
"identity": { "scope": "user", "id": "u_412" } }' # optional: binds the URL to one person
# → { preview, token, signedUrl }
# preview: id, port, url, path, public, identity, createdAt, expiresAt, revokedAt
# signedUrl: the url with the one-shot token on it, ready to hand to somebody
POST /v1/previews/list { "sessionId": "ses_…" }
POST /v1/previews/revoke { "id": "pv_…" }The three are in the reference; the typed client does not wrap them yet.
mint costs data and revoke costs control: publishing a port is something an
agent does in the course of its work, and taking one away is an operator action.
The credential is not in the hostname
The host carries identity; the request carries the credential.
| Where | When |
|---|---|
?cereal_preview=<jws> | The first navigation. Exchanged for a cookie and dropped. |
cereal_preview cookie | Everything after: subresources, XHR, the WebSocket. |
Authorization: Bearer <jws> | A programmatic client. |
The initial navigation exchanges the query token for a host-scoped session credential and redirects to the URL without the token. Treat the full signed URL as a credential; avoid sharing it in public logs or messages.
sandbox.preview.auth: "public" skips all of it. It is a setting you opt into on
purpose, and previews.list shows which grants are public.
A grant outlives its tokens
The URL is stable and the credential rotates. A grant lasts a day by default; a token an hour. Revocation is the grant row, which the route re-reads every few seconds, so a revoke takes effect within that window.
A preview never wakes a machine
A preview request does not resume a stopped or snapshotted sandbox. Resume it through a sandbox tool call or the sandbox API, then restart the application process if needed. A filesystem snapshot does not preserve running processes.
Releasing the sandbox revokes its preview grants. After resuming, expose the port again and use the returned URL.