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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
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.