Previews

client.previews exposes an HTTP service running inside a sandbox at an authenticated public URL like https://p-a1b2c3.crownest.dev. Preview access requires authentication in v1: API-key access by default or a private token link for browser handoff. CrowNest strips its own cookies, the Authorization header, and Referer 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: { authMode?: "authenticated" | "token"; port: number },
): Promise<CreatePreviewResponse>

await sandbox.commands.run("python3 -m http.server 8000", {
  background: true,
});

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

Create a token-mode preview instead when you need a browser-openable private link:

const { preview: tokenPreview, previewToken } = await sandbox.previews.create({
  authMode: "token",
  port: 8000,
});
console.log(`${tokenPreview.url}?cn_token=${previewToken}`);

CreatePreviewResponse contains { preview, previewToken? }. previewToken is returned only when a new token-mode preview is created; reads, lists, and deduped creates cannot recover it.

A sandbox can hold up to 3 active previews, and an org up to 10. Creating one past either limit fails with quota_exceeded.

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<ListPreviewsResponse>

const previews = await client.previews.list(sandbox.id);
for (const preview of previews.data) {
  console.log(preview.url);
}

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 or token), 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.