# Add Health Checks to a Phoenix LiveView App

Yes. An agent adds a /health route that checks the Repo, points your Fly.io http check at it, proves it with a controller test, and opens a PR.

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

## What the agent does

The agent starts with what the platform can see today. In an app laid out like fly-apps/live_beats, `fly.toml` has one `[[services.tcp_checks]]` block with a 15 s interval, a 2 s timeout and a 20 s grace period, so Fly only learns that port 4000 accepts a connection; it cannot tell a healthy release from one whose `DATABASE_URL` points at a database that stopped answering. `lib/live_beats_web/router.ex` has no route for it either: `GET /` is `RedirectController.redirect_authenticated`, which sends a signed-out probe to `/signin` with a 302, and the `:api` pipeline, with only `plug :accepts, ["json"]`, is defined and never piped through. `config/runtime.exs` raises at boot if `DATABASE_URL`, `SECRET_KEY_BASE`, `FLY_APP_NAME` or the GitHub client id is missing, so a bad boot already fails loudly; what is missing is a signal for a node that booted and then lost its database.

It adds the route where the unused pipeline already is. A `HealthController` with a `show` action runs `Ecto.Adapters.SQL.query(LiveBeats.Repo, "SELECT 1", [])` and answers `200` with `{"status": "ok"}`, or `503` with `{"status": "error", "database": "unreachable"}` when the query raises `DBConnection.ConnectionError`. The route is `get "/health", HealthController, :show` in a scope that pipes through `:api`, outside `live_session` and the `:browser` pipeline, so no session is fetched, no CSRF token is checked and no root layout renders. The action puts `cache-control: no-store`, so a proxy never serves a stale `ok`, and it does not touch Presence, the `WhisperServing` or the FLAME pool, which only exist on the parent node (`application.ex` filters them out when `FLAME.Parent.get()` is set) and would make the check lie on a runner.

Then it points the platform at the route. `fly.toml` keeps the TCP check and gains an `[[services.http_checks]]` block for `GET /health` with the same 15 s interval, a 5 s timeout and a 30 s grace period, the extra grace because the release command `/app/bin/migrate` runs before the app starts and Whisper loads from `BUMBLEBEE_CACHE_DIR` at boot. The Dockerfile already installs `curl` in the runner image, so a `HEALTHCHECK` line with `curl -fsS http://localhost:4000/health` goes in for whoever runs the image outside Fly.

In its sandbox the agent starts Postgres, runs `mix setup`, and writes `test/live_beats_web/controllers/health_controller_test.exs` on `LiveBeatsWeb.ConnCase`: one test asserts `GET /health` returns `200` with `%{"status" => "ok"}`, and a second stops the sandbox connection and asserts `503`. It runs `mix test test/live_beats_web/controllers/` and `mix format --check-formatted`, then `curl -i localhost:4000/health` against a running `mix phx.server`, and pastes both outputs into the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a health check endpoint to this Phoenix LiveView app. Read lib/live_beats_web/router.ex, lib/live_beats/application.ex, lib/live_beats/repo.ex, config/runtime.exs, fly.toml and the Dockerfile first. Add a HealthController whose show action runs SELECT 1 through the Repo and answers 200 {\"status\":\"ok\"} or 503 when the database is unreachable, with cache-control: no-store. Route it as GET /health through the existing :api pipeline, not :browser, outside any live_session. In fly.toml keep the tcp check and add an http check for /health with a 30 s grace period. Add a HEALTHCHECK to the Dockerfile using the curl already installed in the runner stage. Write a controller test on LiveBeatsWeb.ConnCase for the 200 and the 503 case. Run mix test for the controllers directory and mix format --check-formatted, start the server and curl /health, and quote both in the pull request. Open a pull request.",
  "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

What comes back is a pull request adding `lib/live_beats_web/controllers/health_controller.ex`, a route in `router.ex`, the `http_checks` block in `fly.toml`, a `HEALTHCHECK` in the Dockerfile and the new test file. The description quotes the `mix test` summary for the controllers directory, the `curl -i` output with the `200`, the JSON body and the `cache-control` header, and the lines of `fly.toml` that changed.

The run's record keeps the full transcript of the test run and the server boot, including the Repo connecting to the sandbox's Postgres and the first request logged by `Plug.Telemetry`. A reviewer who wants to see the 503 path can read the test that forces it rather than take the controller's word.

Before merging, a reviewer decides the grace period: 30 s suits a release whose migrate step is fast and whose Whisper model is already cached in the image, and a longer one suits a first deploy on a fresh volume. They also decide whether `restart_limit` on the http check should stay at Fly's default or match the `0` the TCP check sets.

## Run it on every uptime alert

This is the job to run when the monitor fires and nobody has told the app it is sick. In the Project for the repository, an automation with the prompt above and a `webhook` trigger takes the alert body from Betterstack, Checkly or Grafana; the handler sends the trigger's URL an `Idempotency-Key` made from the alert id, so a re-delivered alert does not start a second run. The trigger adds the payload after the prompt, so the run reads which host failed and from where.

The first run of that automation adds the endpoint. Later runs, on a repository that already has `/health`, read the alert, run the check against the failing host from the sandbox, and open a pull request only when the check itself needs to change, such as adding the uploads mount under `BUCKET_MOUNT` to what it verifies. Each run opens its own branch and links the alert in the description.

## Why run it on Rush?

A health route is twenty lines and a config block, and it is the kind of change that gets written without ever being exercised: the route goes through `:browser` and a probe without a session is redirected, or the check queries a service that a FLAME runner does not start, or the grace period is shorter than the migrate step and every deploy restarts itself. In a Rush sandbox the agent boots the app against a real Postgres, hits the route with curl, forces the failing case in a test, and the pull request quotes what it saw.

The transcript stays with the run, so when the same app is deployed somewhere other than Fly the next person can read exactly what the check verifies and why the grace period is what it is. Across many Phoenix apps the job runs in parallel, one sandbox each, with the same prompt and a different `fly.toml` in every result.

## Frequently asked questions

### Why not point the check at the home page?

Because `GET /` is a redirect to `/signin` for a visitor without a session, and a check that follows it only proves the router works. A route through `:api` with a `SELECT 1` proves the node can reach its database, which is the failure a restart actually fixes.

### Does the check restart a node whose Whisper model has not loaded?

No. The controller does not touch `LiveBeats.WhisperServing`, because `application.ex` starts it only on the parent node or outside the Fly backend; a check that depended on it would mark a FLAME runner unhealthy forever. The grace period covers the model loading on the parent.

### What does the 503 test actually do?

It checks out the Ecto sandbox connection and closes it before the request, so the query in the controller raises `DBConnection.ConnectionError`, then asserts the status and the JSON body. It runs in the same `mix test` as the 200 case, with no second database.

### Will the http check replace the tcp check?

The pull request keeps both. The TCP check still catches a process that never bound port 4000, and the http check catches one that bound it and cannot query. Removing the TCP block is a one-line follow-up if the team prefers a single check.

### Can the check verify the uploads mount too?

Yes. Say so in the prompt and the agent adds a `File.stat` of `uploads_dir` from the `:files` config, which is the s3fs mount at `BUCKET_MOUNT` in production, and reports it as a second key in the JSON body. It is left out by default because a mount that is slow to attach would restart a node whose database is fine.

## More Phoenix LiveView jobs

- [Add i18n with Gettext to a Phoenix LiveView App from a Linear Issue](https://getrush.ai/run/add-i18n/phoenix-liveview/)
- [Add Prometheus Metrics to a Phoenix LiveView App](https://getrush.ai/run/add-prometheus-metrics/phoenix-liveview/)
- [Add Live Search to a Phoenix LiveView Page from a Linear Issue](https://getrush.ai/run/add-song-search/phoenix-liveview/)

## The same job on other stacks

- [Add Health Checks to a Quarkus Service](https://getrush.ai/run/add-health-checks/quarkus/)
- [Add a Health Check Route to a React Router App with a Custom Express Server](https://getrush.ai/run/add-health-checks/react-router/)
- [Add Health Check Endpoints to a Rocket App](https://getrush.ai/run/add-health-checks/rocket/)

## 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/)
