kosa8 docs

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)

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

StatusWhy
401Private preview without a valid token, or the link has expired.
404No preview at this address (rotated or closed).
410The sandbox was deleted or passed its delete_after.
502Nothing listens on that port, or it listens on 127.0.0.1 only.
503The 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