Previews

client.previews exposes an HTTP service running inside a sandbox at an authenticated public URL like https://p-a1b2c3.preview.crownest.dev. Preview access requires authentication in v1: org members or API keys permitted for the sandbox's project. CrowNest strips its own cookies and the Authorization header before proxying requests to your app.

A SandboxHandle exposes sandbox.previews.create and sandbox.previews.list without the sandboxId argument.

create

Expose a port from the sandbox. One active preview exists per sandbox and port; creating a preview for the same port again returns the existing one.

create(
  sandboxId: `sbx_${string}`,
  input: { port: number },
): Promise<Preview>

await sandbox.commands.start("python -m http.server 8000");

const preview = await client.previews.create(sandbox.id, { port: 8000 });
console.log(preview.url); // https://p-a1b2c3.preview.crownest.dev

Error codes: invalid_request, not_found, sandbox_destroyed, quota_exceeded. If the service behind the preview stops responding, requests to the preview URL fail with preview_unavailable.

list

List previews for a sandbox.

list(sandboxId: `sbx_${string}`): Promise<readonly Preview[]>

const previews = await client.previews.list(sandbox.id);

get

Fetch a single preview by ID.

get(previewId: `prv_${string}`): Promise<Preview>

const preview = await client.previews.get("prv_abc123");

Error codes: not_found, forbidden.

revoke

Revoke a preview so its URL stops serving traffic. The operation is idempotent and returns the preview record with revokedAt set.

revoke(previewId: `prv_${string}`): Promise<Preview>

await client.previews.revoke(preview.id);

Error codes: not_found, forbidden.

Preview object

The Preview type includes id (prv_ prefix), slug (DNS-safe, like p-a1b2c3), url, orgId, projectId, sandboxId, port, authMode (authenticated in v1), createdAt, expiresAt, and revokedAt.

Previews end with their sandbox: when the sandbox is destroyed, the preview URL stops working.

Next steps

• Commands — start the service the preview points at.
• Previews concept — authentication and proxy behavior.
• Errors — error codes and retry guidance.