Previews

A preview exposes an HTTP service running inside a sandbox at an authenticated URL. Start a server in the sandbox, create a preview for its port, and CrowNest proxies requests to it — without making the sandbox publicly reachable.

Authenticated only in v1

All previews require authentication in v1; authMode accepts only authenticated, and any other value returns unsupported_preview_auth_mode. Access is limited to members of the sandbox's organization and to API keys permitted for the sandbox's project. Unauthenticated public previews aren't available.

Preview URLs

Creating a preview returns a slug (DNS-safe, like p-a1b2c3) and a url of the form:

https://p-a1b2c3.preview.crownest.dev

Requests to that hostname are proxied to the chosen port inside the sandbox. If the port isn't responding, the proxy returns preview_unavailable.

One preview per sandbox and port

Each sandbox can have one active preview per port. Create one with POST /v1/sandboxes/{id}/previews and a body containing port (an integer from 1 to 65535) and optionally sourceCommandId to link the preview to the command that started the server. Creating a preview for a sandbox and port that already has an active preview returns the existing preview rather than an error, so creation is safe to retry.

What CrowNest strips

Before proxying a request to your app, CrowNest removes its own credentials:

• CrowNest's own cookies.
• The Authorization header.

Your app behind the preview never sees the caller's CrowNest credentials. If your app needs authentication of its own, use a separate mechanism such as your own header or cookie.

Revocation and lifecycle

Revoke a preview with DELETE /v1/previews/{previewId}; the operation is idempotent, and the preview records a revokedAt timestamp. Previews are tied to their sandbox: when the sandbox is destroyed — killed, expired, or otherwise — its previews stop working. Creating a preview on a destroyed sandbox returns sandbox_destroyed.

Next steps

• Sandboxes — the lifecycle previews are tied to.
• Commands — start the server a preview points at.
• API keys and scopes — the preview:* scopes and project restrictions that govern access.
• Previews API reference