Skip to main content
Preview URLs route a hostname such as https://3000-{sandbox-id}.sandbox.superserve.ai to a process listening inside your sandbox. Use an explicit preview policy and publish only the ports you intend to expose.

​
Access policies

The sandbox’s previewAccess / preview_access selects strict publication and sets the default access for each newly published port: Every published port stores its own public or private access mode. Changing the sandbox default does not rewrite existing ports, so public and private ports can coexist in one sandbox. legacy_public exists only for sandboxes created before the publication migration. New sandboxes default to strict public when the field is omitted. The compatibility mode cannot be selected through create or update APIs.
Moving a legacy sandbox to public or private immediately closes every port that has not been published. Publish the intended ports before changing the policy if you need a seamless transition.

​
Choose the sandbox default

Use public when new ports should be internet-accessible by default. Use private when new ports should require a credential by default. You can change the default later with update; already-published ports keep their own mode:

​
Publish a port

Start the service, then publish its port. Omit the access option to use the sandbox default for a new port. An omitted option preserves the mode of an already-published port; pass an explicit mode to override just that port.
getPreviewUrl / get_preview_url only constructs the hostname. It does not publish the port or add credentials. Ports must be integers from 1024 through 65535; port 49983 is reserved for sandbox control traffic and cannot be published. List the current server-side publication state with listPreviewPorts() / list_preview_ports(). The result includes the sandbox default and every published port’s access, but never includes tokens.

​
Authenticate a private port

Private preview credentials are scoped to one published port. A token for port 3000 cannot open port 8080 on the same sandbox.

​
Machine clients and reverse proxies

Mint a token and send it using the header name returned by the API:
Omit the expiry to keep a token valid until that port is rotated or unpublished. For limited-lived machine credentials, pass expiresInSeconds / expires_in_seconds from 1 to 604800 seconds.

​
Browsers, iframes, and WebSockets

Browsers cannot attach a custom header to a navigation. Request a signed URL instead:
The SDK defaults signed links to 60 seconds. On first navigation, the edge proxy verifies the query token, stores it in a secure host-scoped cookie, and redirects to the same URL without the token. Asset requests and WebSocket upgrades then use the cookie automatically.
Treat signed URLs as secrets until the initial redirect removes their query token. Avoid logging them or placing them in analytics and referrer data.

​
Revoke access

Rotate a port to invalidate all of its existing header tokens, signed links, and browser cookies without affecting other ports:
Unpublishing closes the port at the edge and revokes its credentials:
Unpublish is idempotent and retry-safe. Under a strict policy the edge returns 404 for an unpublished port before revealing sandbox status or checking a credential.

​
MCP and console

The console’s Preview panel uses the same server-backed published-port list. It mints a signed browser URL for each private port without displaying the credential; public sibling ports keep clean URLs. The MCP sandbox_preview_url tool publishes the requested port. It returns a clean URL when that port is public and a one-hour signed URL by default when it is private. Re-publishing without an access override preserves an existing port’s mode. Set expires_in_seconds to choose another private-link lifetime.