Skip to main content
WebSocket endpoints stream responses to the client, enabling real-time, bidirectional communication.

Required changes

Setting up a WebSocket endpoint requires a custom runtime. Configure it in cerebrium.toml:
Fields:
  • port: The port the app listens on inside the container.
  • entrypoint: The command to start the app. This example uses Uvicorn to run a FastAPI app in main.py.
  • healthcheck_endpoint: Confirms instance health. Defaults to a TCP ping on the configured port. A non-200 response marks the instance as unhealthy, triggering a restart if it does not recover.
  • readycheck_endpoint: Confirms the instance is ready to receive traffic. Defaults to a TCP ping on the configured port. A non-200 response removes the instance from request routing.

Things to note

  • Custom Runtime Required: WebSocket endpoints require a custom runtime to control how the app runs inside the container.
  • WebSocket URL: Requests must use a wss:// URL. The client must support secure WebSocket connections.

Session Duration

A WebSocket connection is treated as a single long-running request and is bounded by response_grace_period in cerebrium.toml. The default is 900 seconds (15 minutes). When the grace period elapses, Cerebrium terminates the connection with a GatewayTimeout error. Raise the value to match the longest session your app needs to support:
The same value governs how long an instance drains in-flight WebSocket sessions during a shutdown or migration. Custom runtimes must handle SIGTERM to close open sockets gracefully before the grace period expires; see Graceful Termination.

Making a request

Test the WebSocket endpoint using websocat, a command-line WebSocket client:

Implementing the WebSocket Endpoint

Example WebSocket endpoint using FastAPI:

Additional Info

Client-side Implementation: Handle the WebSocket connection properly on the client, including error handling and reconnection logic.