WebSockets & Server-Sent Events
Add real-time features to your deployment using WebSockets or Server-Sent Events.
Phemeral supports long-lived, real-time connections to your deployments using both WebSockets and Server-Sent Events (SSE).
- Server-Sent Events (SSE) — a one-way stream from your server to the client over a single HTTP response. Good for live feeds, notifications, progress updates, and token streaming.
- WebSockets — a two-way connection between client and server. Good for chat, collaborative editing, multiplayer, and anything where the client also sends messages.
Framework Support
WebSockets require an ASGI app (e.g., FastAPI or Django with Channels). Flask runs under WSGI, which has no WebSocket support. Use an ASGI framework if you need WebSockets. SSE works on every supported framework.
Flask runs under gunicorn with a single synchronous worker by default. Each open SSE stream holds that worker for the life of the connection, blocking other requests to the deployment. To serve more than one or two concurrent streams, raise the worker count (or use an async worker) with a custom start command.
gunicorn app.main:app --bind 0.0.0.0:8000 --workers 4Keep Connections Alive
Phemeral closes a connection that has sent no data in either direction for more than five minutes. To keep a connection open, make sure something flows across it on an interval.
WebSockets: send a ping/pong frame (or any message) at least once every 5 minutes. If more than five minutes pass with no traffic, the connection is dropped. Most servers do this for you, uvicorn sends WebSocket pings automatically (every 20 seconds by default), which keeps the connection alive with no extra code. If you turn automatic pings off, send an application-level message at least once every 5 minutes yourself.
Server-Sent Events: emit an event or a comment line at least once every 5 minutes. A comment is any line beginning with a colon, which clients ignore:
yield ": keepalive\n\n" # emit on an interval to hold the connection openReconnect After Disconnects
Design your client to reconnect automatically:
- SSE — the browser's
EventSourcereconnects on its own by default, so most SSE clients need no extra handling. - WebSockets — add reconnect logic to your client: when the socket closes, open a new one, ideally with a short backoff between attempts.
How Real-Time Connections Are Billed
A WebSocket or SSE connection is metered across Phemeral's standard compute dimensions:
- Requests — each connection counts as one request when it opens.
- Compute — an open connection keeps your deployment running, so it accrues compute (RAM GB-hours) for the whole time it stays open, including idle periods with no messages.
- Data transfer — outbound data sent from your app to the client over the connection is metered.
Because an open connection keeps your deployment from scaling to zero, many long-lived or idle connections can accrue compute charges even when little data is flowing. Close connections your client no longer needs.