Skip to content

Published sessions

A session that serves HTTP can be published: it gets a public URL (https://<slug>.at.beta.barista.sh) that wakes it on demand.

# the workload binds 0.0.0.0:$PORT (the node injects PORT)
curl -X POST -H "Authorization: Bearer $KEY" \
  https://beta.barista.sh/v1/sessions/<name>/publish   # → slug = <name>-xxxx (unique)

With no slug in the body, a unique slug is minted (<name>- plus four random characters) — the public namespace is shared across all tenants, so bare names would collide. Re-publishing keeps the slug you already have (the URL is stable); pass {"slug": "…"} to request an exact slug, which is granted first-come (409 if another session holds it). The response carries the final slug and public_url.

How the path works

The node forwards the workload's port through its ingress and reports a dialable address; the gateway resolves your slug, wakes the session if it's paused (wake-on-request — the first hit after a nap pays a moment of resume latency), validates the address against its trusted-node allowlist, and proxies. TLS for the public hostname is issued on demand, and only for slugs that are actually published — an unpublished name never gets a certificate, let alone a route.

The contract for your app

  • Bind 0.0.0.0:$PORT. The node injects PORT into the workload's environment; the forwarded address is sticky for the session's lifetime, across pause/resume.
  • Be self-contained. The image (or template) must carry the app; a published session is reachable without any key, so it should serve exactly what you mean to expose — and nothing else lives on that origin.
  • Expect naps. An idle-paused app doesn't consume compute; the wake is transparent to callers beyond first-hit latency. State in memory survives.

Unpublishing and deletion

DELETE /v1/sessions/<name>/publish removes the slug; deleting a session releases its slug automatically, so names and slugs are reusable immediately.

Live example: the counter demo is a published session — pause it and the next visit wakes it with its count intact.