Guides / kosa8 Cloud / Preview URLs
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 anHttpOnly,Securecookie 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 aReferer. - From a program, send the token in a header:
X-Kosa8-Preview-Token: eyJz…. Your app's ownAuthorizationheader and cookies reach it untouched; kosa8's token and cookie are removed first. - A link works for
expires_in_sseconds: 3600 by default, 60 to 604800 (7 days). Ask for another withPOST /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_configureduntil preview URLs are switched on for your kosa8 Cloud, and501 not_availableon a host that does not serve them yet.