# Add WebSockets to a Litestar App

Yes. An agent adds a typed websocket_listener and a channels broadcast to your Litestar app, tests both with TestClient, keeps mypy strict happy, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-websockets/litestar/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the app and the rules it is held to first. In a project laid out like litestar-org/litestar-hello-world, `app.py` is the whole service: `async_hello_world` on `GET /async`, `sync_hello_world` on `GET /sync` with `sync_to_thread=False`, both annotated `Dict[str, Any]` with a `# noqa: UP006` because `requires-python` starts at 3.8, and an `__all__` tuple the `ensure-dunder-all` pre-commit hook checks. `pyproject.toml` depends on `litestar[standard]>=2.4.1`, which `pdm.lock` resolves to 2.4.1 together with `websockets` 12.0 through uvicorn's extras, so no new dependency is needed for a socket endpoint. Ruff runs with `select = ["ALL"]` at line length 120, mypy in `strict` mode with `litestar[standard]` and `pytest` as additional dependencies, plus pyright, slotscheck and codespell, all through `.pre-commit-config.yaml`; `tests/test_app.py` has two tests using `litestar.testing.TestClient` against the imported `app`, and `.github/workflows/ci.yaml` runs pre-commit on 3.11 and the tests on 3.8 through 3.11 with PDM.

Two endpoints cover what people mean by websockets. The first is an echo with typed data: `@websocket_listener("/ws")` on a handler that takes `data: Dict[str, Any]` and returns a dict with the message and a server timestamp; Litestar parses the incoming frame as JSON because of the annotation, serialises the return value, and handles accept, receive loop and disconnect itself. A `connection_lifespan` async context manager logs the connection and its close, which is where a real app would authenticate or register the client. The second is a broadcast on `/chat` built on `litestar.channels`: a `ChannelsPlugin` with `MemoryChannelsBackend` and `channels=["chat"]` goes into the app's `plugins`, a `POST /chat` handler takes a message and calls `channels.publish(data, "chat")`, and a `@websocket("/chat")` handler accepts the socket, subscribes with `async with channels.start_subscription(["chat"]) as subscriber` and runs `subscriber.run_in_background(socket.send_text)` until the client leaves. The plugin reaches both handlers as the `channels` dependency without an import in the handler signature's module.

The code is written to pass the repository's own gates. Every handler keeps the `Dict`, `Any` and `Optional` spellings from `typing` for 3.8, the new names go into `__all__`, the listener's return type is explicit so mypy strict accepts it, and the broadcast handler catches `WebSocketDisconnect` so a closed tab does not log a traceback. `app = Litestar(route_handlers=[...], plugins=[channels_plugin])` is the one line of the existing file that changes shape; the two HTTP handlers stay as they are.

`tests/test_app.py` gains four tests in the existing `TestClient` style. `client.websocket_connect("/ws")` sends a JSON frame with `send_json` and asserts the echoed message and a timestamp key with `receive_json`; a second test sends a text frame that is not JSON and asserts the socket closes. For the broadcast, two sockets connect to `/chat`, a `POST /chat` is sent, and both receive the text; a fourth test checks a subscriber that disconnects stops receiving. The agent runs `pdm install`, `pre-commit run --all-files` and `pdm run pytest` on Python 3.11 and 3.8 in its sandbox, fixes what ruff's full rule set and mypy strict raise, and opens the pull request with that output.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add WebSocket support to this Litestar app and open a pull request. Read app.py, pyproject.toml, pdm.lock, tests/test_app.py, .pre-commit-config.yaml and .github/workflows/ci.yaml first. Add no dependency unless pdm.lock lacks what the endpoints need. Add a websocket_listener on /ws that takes data typed as a dict, returns the message with a server timestamp, and has a connection_lifespan that logs connect and disconnect. Add a ChannelsPlugin with MemoryChannelsBackend and a chat channel to the app's plugins; add POST /chat that publishes the body to the channel and a websocket handler on /chat that subscribes and forwards every message with run_in_background until the client disconnects. Keep Python 3.8 compatible typing with the noqa the file already uses, update __all__, and keep ruff select ALL, mypy strict, pyright and slotscheck passing. Extend tests/test_app.py with TestClient websocket_connect tests for the echo, a non-JSON frame, a broadcast to two clients and a disconnected subscriber. Run pdm install, pre-commit run --all-files and pdm run pytest on Python 3.11 and 3.8 until all pass, then open a pull request listing the routes and what each test proves.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `app.py` and `tests/test_app.py` and nothing else: `pyproject.toml` and `pdm.lock` are untouched because `websockets` was already resolved. Its description lists the routes, `GET /async`, `GET /sync`, `WS /ws`, `POST /chat` and `WS /chat`, says what each new test asserts, and quotes the `pre-commit` and `pytest` output from both Python versions in the sandbox.

It names the two decisions a reviewer will ask about: the in-memory channels backend holds subscribers in one process, so the description points at `RedisChannelsPubSubBackend` for more than one worker, and the echo listener parses JSON without validating it, which is what Litestar's listener does, so a schema is a follow-up with a `msgspec.Struct` annotation.

Before merging, a reviewer decides whether `/chat` needs the same guard as any future authenticated route, whether the memory backend is right for the deployment, and whether `ws_handler_send_history` on the plugin should replay recent messages to a client that joins late.

## Run it on every Linear issue labelled realtime

An automation on the Project with a `linear` trigger on `linear.issue.labeled`, `realtime` in `config.labels`, and the prompt "this issue names a page or event that should push updates to connected clients; add a channel and a publish call where the event happens, extend the tests, and open a pull request" starts one run per labelled issue once the plugin exists. The trigger adds the issue after the prompt and fills in nothing else, so an issue about order status gets an `orders` channel and a publish in the handler that changes an order.

A team with several Litestar services sends this body once per repository from its own server, each `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own app: a service already running several uvicorn workers gets the Redis backend from the start, and one with `JWTAuth` configured gets the socket routes placed behind it.

## Why run it on Rush?

Litestar's socket support is typed and small, and the mistakes hide in the typing: a listener whose return annotation mypy strict rejects, a `typing` import that breaks 3.8, a handler that forgets `__all__` and fails a hook, a subscription that is never closed when the client goes away. The agent fits the change to the repository's own hooks and runs them, with the tests, on both ends of the supported Python range in its sandbox, where it can hold two sockets open against the app at once.

The hook output, the test runs and the diff stay with the run, so a reviewer sees that ruff with every rule, mypy strict, pyright and slotscheck pass and that each socket route's behaviour is asserted, including the disconnect path. A team with several Python services sends the same request to all of them at once.

## Frequently asked questions

### Does this add a dependency?

Not in this app. `litestar[standard]` brings uvicorn's standard extras, and `pdm.lock` already resolves `websockets` 12.0, which uvicorn uses for the socket protocol. The channels plugin lives in `litestar.channels` inside the framework. An app on a leaner extra would get the dependency added and the lock updated.

### What is the difference between the listener and the raw handler?

`websocket_listener` runs the accept and receive loop for you and calls your function once per frame with the data converted to its annotation; it suits request-reply. `websocket` hands you the `WebSocket` and you write the loop, which the broadcast needs because it sends whenever the channel does, not when the client speaks.

### Will the broadcast work with several server processes?

Not with `MemoryChannelsBackend`, which keeps subscribers in one process. The pull request names `RedisChannelsPubSubBackend` as the swap, one import and one constructor argument, so every worker sees every publish. The handlers and tests do not change.

### How are the socket tests run without a server?

`litestar.testing.TestClient` opens a socket to the app in-process with `websocket_connect`, and the returned session has `send_json`, `receive_json`, `send_text` and `receive_text`. The agent keeps the same `with TestClient(app=app) as client` shape the two existing tests use.

## More Litestar jobs

- [Upgrade Python Dependencies Weekly for a Litestar App](https://getrush.ai/run/upgrade-python-dependencies/litestar/)
- [Write Pytest Tests for a Litestar App](https://getrush.ai/run/write-pytest-tests/litestar/)
- [Add API Key Authentication to a Litestar App](https://getrush.ai/run/add-api-key-auth/litestar/)

## The same job on other stacks

- [Add a WebSocket Endpoint to a Vapor App from a Linear Issue](https://getrush.ai/run/add-websockets/vapor/)
- [Add WebSockets to an aiohttp App](https://getrush.ai/run/add-websockets/aiohttp/)
- [Add WebSockets to a Cloudflare Worker with Durable Objects](https://getrush.ai/run/add-websockets/cloudflare-workers/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
