> ## Documentation Index
> Fetch the complete documentation index at: https://cerebrium-mintlify-3d28189b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cerebrium's documentation MCP server is available at https://cerebrium.ai/docs/mcp for searching and querying these docs directly. Install the Cerebrium agent skill with `npx skills add https://cerebrium.ai/docs`. Append .md to any docs page URL to fetch that page as plain Markdown. API keys and authentication tokens are created in the Cerebrium dashboard at https://dashboard.cerebrium.ai.

# WebSocket Endpoints

> Configure WebSocket endpoints on Cerebrium with a custom runtime, control session duration via response_grace_period, and handle SIGTERM.

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`:

```toml theme={null}
[cerebrium.runtime.custom]
port = 5000
entrypoint = "uvicorn main:app --host 0.0.0.0 --port 5000"
healthcheck_endpoint = "/health"
readycheck_endpoint = "/ready"
```

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:

```toml theme={null}
[cerebrium.scaling]
response_grace_period = 3600  # 1 hour, in seconds
```

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](/scaling/graceful-termination).

## Making a request

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

```bash theme={null}
websocat wss://api.cerebrium.ai/v4/p-xxxxxxxx/<your-app-name>/<your-websocket-function-name>
```

## Implementing the WebSocket Endpoint

Example WebSocket endpoint using FastAPI:

```python theme={null}
# In main.py:
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/your-websocket-function-name")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    await websocket.send_text("Hello, WebSocket!")
    await websocket.close()
```

## Additional Info

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

```javascript theme={null}
// Example using JavaScript in a browser
const socket = new WebSocket(
  "wss://api.cerebrium.ai/v4/p-xxxxxxxx/<your-app-name>/<your-websocket-function-name>",
);

socket.onopen = function (event) {
  console.log("WebSocket is open now.");
};

socket.onmessage = function (event) {
  console.log("Received data: " + event.data);
};

socket.onclose = function (event) {
  console.log("WebSocket is closed now.");
};

socket.onerror = function (error) {
  console.error("WebSocket error observed:", error);
};
```