Skip to main content
A preview exposes a port inside a sandbox as an HTTPS URL, so you can view a dev server, API, or any other listener from a browser.

​
Creating a preview

MCP: the preview_create tool exposes this, with capability_jws deliberately dropped from the result — see below. Request body (PreviewCreateRequest):
​
integer
required
Port to expose, 1024–65535.
​
string
default:"token"
token or public (see below).
​
string
Display metadata only, at most 80 UTF-8 bytes.
Create also accepts an Idempotency-Key header — see Idempotency. Returns 201 with PreviewCreateResponse:
​
object
required
The created Preview (see fields below).
​
string
required
A capability token for the token-mode browser exchange described below.
capability_jws is returned only by create — it is never included in the list response. Store it if you need the token-mode exchange; there’s no way to retrieve it again later. This is a deliberate security property, not an oversight.

​
Preview fields

​
string
required
Matches ^pv-[a-z2-7]{26}$.
​
string
required
The owning sandbox.
​
integer
required
The exposed port, 1024–65535.
​
string
required
token or public.
​
string
Display metadata only, at most 80 UTF-8 bytes.
​
string
required
Token-free base preview URL.
​
integer
required
Creation time.

​
Auth modes

auth_mode is one of two values — not private/public:
  • token (default) — access is gated by the Roxy browser exchange described below.
  • public — anyone with the URL can view it; no exchange required.

​
The token-mode browser exchange

In token mode, the client navigates once to preview.url with ?bonya_token=<capability_jws> appended. Roxy (the preview proxy) validates the token, sets a host-scoped Secure, HttpOnly cookie, and redirects to the same URL with bonya_token stripped — before any guest content is rendered. After that one exchange, the cookie carries the session; the token itself should not be stored in URLs or logs beyond that single navigation. Each SDK wraps this exchange in a previewBrowserUrl-style helper, which builds the one-time URL from the capability_jws returned by create. There’s no cURL or CLI example for this step — it’s a browser navigation, not a request/response call — and no MCP tool, since preview_create’s MCP result deliberately omits capability_jws in the first place.
Open it once and let the cookie carry the session — the URL itself should not be shared, since anyone who receives it holds the sandbox’s data-plane capability until it expires. It throws/raises/errors (per SDK) on a public preview, which has no token to exchange.

​
Listing previews

MCP: the preview_list tool covers this. Returns PreviewListResponse: { "previews": [ ...Preview ] }. As noted above, list never includes capability_jws — only create does.

​
Deleting a preview

MCP: the preview_delete tool covers this, and is likewise idempotent.
Delete is idempotent and deliberately avoids leaking cross-org existence — deleting a preview that doesn’t exist (or belongs to another organization) behaves the same as deleting one that does, rather than distinguishing the two cases.
Returns 204 on success.

Sandboxes

Idempotency