# Preview URLs

A preview opens one port of a sandbox at an https address of its own, so a person or a program can use the dev server, app or API your agent started. Previews are private unless you say otherwise: the link carries a signed token, and nobody without it gets in.

## Open a port

Start the server inside the sandbox on `0.0.0.0` (a server on `127.0.0.1` cannot be reached from outside its container), then ask for a preview with a key that has the `sandboxes:write` scope.

```
curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/previews \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"port":3000}'
# {"preview":{"port":3000,"public":false,
#   "url":"https://3000-k2v…q7.<preview domain>/?kosa8_preview=eyJz…",
#   "host":"3000-k2v…q7.<preview domain>","token":"eyJz…","expires_at":"2026-11-14T13:00:00.000Z",…}}
```

The address is random and names the port; the sandbox id is never in it. Each preview has its own origin, so one preview's page cannot read another's cookies.

## Private (the default)

- **In a browser**, open `url`. The first visit trades the token for an `HttpOnly`, `Secure` cookie on that address alone and redirects to the same page without the token, so it does not stay in the address bar or leak in a `Referer`.

- **From a program**, send the token in a header: `X-Kosa8-Preview-Token: eyJz…`. Your app's own `Authorization` header and cookies reach it untouched; kosa8's token and cookie are removed first.

- A link works for `expires_in_s` seconds: 3600 by default, 60 to 604800 (7 days). Ask for another with `POST /v1/sandboxes/{id}/previews/{port}/link`.

## Public

For a webhook receiver or a demo anyone may open, send `"public": true`. The answer has no token and the URL works for anyone who has it. Sending the same port again with `"public": false` closes it to strangers and keeps the address. Opening, changing and closing a preview are recorded in the audit log.

## End every link

```
# move the preview to a new address: every earlier link and cookie stops working
curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/previews/3000/rotate -H "Authorization: Bearer $KOSA8_API_KEY"
# close it
curl -s -X DELETE https://api.kosa8.com/v1/sandboxes/sbx_…/previews/3000 -H "Authorization: Bearer $KOSA8_API_KEY"
# what is open
curl -s https://api.kosa8.com/v1/sandboxes/sbx_…/previews -H "Authorization: Bearer $KOSA8_API_KEY"
```

Deleting the sandbox ends its previews too. A frozen organization's previews answer `423` until it is unfrozen.

## What a visitor can get back

| Status | Why |
|---|---|
| `401` | Private preview without a valid token, or the link has expired. |
| `404` | No preview at this address (rotated or closed). |
| `410` | The sandbox was deleted or passed its `delete_after`. |
| `502` | Nothing listens on that port, or it listens on 127.0.0.1 only. |
| `503` | The sandbox is asleep. Wake it (`POST /v1/sandboxes/{id}/wake`) and reload. |

WebSockets and server-sent events pass through, so dev servers with hot reload work.

## Limits

- At most 20 open ports per sandbox.

- Opening a preview answers `501 previews_not_configured` until preview URLs are switched on for your kosa8 Cloud, and `501 not_available` on a host that does not serve them yet.

---
Source: https://docs.kosa8.com/guides/cloud-previews/
