# Add Health Checks to a Leptos App

Yes. An agent adds /health/live and /health/ready to your Leptos app's Axum server, kept out of the Leptos route list, with Playwright tests and a PR.

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

## What the agent does

The agent reads how the server is assembled before it adds a route, since in a Leptos app the Axum router and the Leptos route list are two different things. In a project made from leptos-rs/start-axum, `src/main.rs` builds the server only under `#[cfg(feature = "ssr")]`: it reads `get_configuration(None)`, calls `generate_route_list(App)` to turn the `<Routes>` in `src/app.rs` into Axum routes, registers them with `.leptos_routes(&leptos_options, routes, …)`, sets `.fallback(leptos_axum::file_and_error_handler(shell))` for static files and the `Page not found.` view, and serves on `site-addr`, `127.0.0.1:3000` in `Cargo.toml`. `Cargo.toml` has `axum` 0.8, `tokio` 1 with only `rt-multi-thread`, `leptos`, `leptos_router`, `leptos_meta` and `leptos_axum` at 0.8, all server crates optional behind the `ssr` feature, with `hydrate` for the WebAssembly side. `src/app.rs` declares one route, `StaticSegment("")`, rendering `HomePage`. There is no `/health`, no `/ready`, and a load balancer that probes the app today gets the full rendered home page.

It adds a `health` module compiled only with `ssr`, with two Axum handlers. `GET /health/live` returns `200` with `{"status":"ok"}` as `axum::Json` and does nothing else, so it stays true while the process runs. `GET /health/ready` runs the checks the prompt names, which for the template is one: that the `site-root` directory from `LeptosOptions` exists and holds the `pkg` bundle, since a server started before `cargo leptos build` finished would serve a shell with no WebAssembly. Each check is a `(name, Result)` pair; a failure answers `503` with the failing names, and both handlers set `Cache-Control: no-store`. The agent registers them with `.route("/health/live", get(live))` and `.route("/health/ready", get(ready))` before `.leptos_routes`, so the fallback never sees them, and keeps the handlers out of `app.rs` so the hydrate build never compiles them. `tokio` keeps `rt-multi-thread` only; nothing new is needed for the checks.

The template tests with Playwright through `cargo leptos end-to-end`, which runs `npx playwright test` in `end2end/` against the server it starts, so the agent adds `end2end/tests/health.spec.ts` beside `example.spec.ts`: a request to `http://localhost:3000/health/live` must answer `200` with `status` equal to `ok`, `/health/ready` must answer `200` with every check named, and `/health/nothing` must still answer with the `Page not found.` view, proving the fallback is intact. It adds a Rust unit test too, calling the ready handler with a `LeptosOptions` whose `site_root` points at an empty temp directory and asserting `503`.

In its sandbox the agent installs the nightly toolchain `rust-toolchain.toml` asks for, adds the `wasm32-unknown-unknown` target, installs `cargo-leptos` and `sass`, runs `npm install` in `end2end`, then `cargo leptos build`, `cargo test --features ssr` and `cargo leptos end-to-end`, so the pull request carries a passing run of the template's own test command and not only a unit test.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add health check endpoints to this Leptos app. Read Cargo.toml, rust-toolchain.toml, src/main.rs, src/app.rs, src/lib.rs, end2end/playwright.config.ts and end2end/tests first. Add GET /health/live, which always answers 200 with a small JSON body, and GET /health/ready, which answers 200 when the site root from LeptosOptions exists with its pkg directory and 503 naming the failed check otherwise, both with Cache-Control no-store. Put the handlers in a module compiled only with the ssr feature and register them on the Axum router before leptos_routes so the file_and_error_handler fallback never handles them; do not add them to the Leptos Routes in app.rs. Write a Playwright test for both endpoints and for a missing /health path still rendering the not-found view, and a Rust unit test for the 503 case. Install the nightly toolchain, the wasm32 target, cargo-leptos and sass, run cargo leptos build, cargo test --features ssr and cargo leptos end-to-end, and open a pull request. Do not change the existing route or the site address.",
  "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 adds `src/health.rs`, registers it in `src/lib.rs` under `#[cfg(feature = "ssr")]`, edits `src/main.rs` to add the two routes, and adds `end2end/tests/health.spec.ts`. Its description pastes the `cargo test` and `cargo leptos end-to-end` output and a `curl -i` of each endpoint from the built server, including the `503` body produced with the site root pointed elsewhere.

A reviewer decides which checks `/health/ready` should run once the app has a database or an upstream API (each is one more `(name, Result)` entry), whether the probes should be unauthenticated on a public host, and whether a Kubernetes manifest or a load balancer config should now point its liveness and readiness probes at the two paths.

## Run it on every new Leptos service

A team that starts services from the same template runs this once per new repository from its own server: one `POST /o/{org}/sessions` per repository, each 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 rather than opening a second pull request. Each run reads its own `main.rs`: a service that already has a database pool in `with_state` gets a readiness check that pings it, and one on `leptos_actix` instead of Axum gets the same two handlers as Actix routes.

The useful repeat is the probe itself. An automation with a schedule trigger in a Project runs every morning, with a `cron` such as `0 7 * * *` in your `timezone`, and the prompt "request /health/live and /health/ready on the staging host and report the status and body of each"; one run a day keeps its output, so a readiness failure after a deploy is seen before a customer sees it.

## Why run it on Rush?

A health route in a Leptos app is easy to put in the wrong place: inside `<Routes>` it ships to the browser bundle and renders a view, after the fallback it is never reached, and without the `ssr` gate it breaks the WebAssembly build. The agent reads the feature flags and the router order first and proves the result with the template's own end-to-end command, nightly toolchain and all.

The toolchain install, the build and the test runs stay with the run and are in the pull request, so a reviewer sees the `503` case exercised and not described. The same request runs across every Leptos service a team keeps at once.

## Frequently asked questions

### Why not add the health route in app.rs?

Because `<Routes>` describes views that are rendered on the server and hydrated in the browser, and `generate_route_list` turns them into Axum routes that return HTML. A probe wants a tiny JSON answer and must not compile into the `hydrate` build; a plain Axum route in a module behind `#[cfg(feature = "ssr")]` does both.

### Does the order of the routes matter?

Yes. `file_and_error_handler` is the router's fallback for anything the Leptos routes do not match, serving static files from the site root or the not-found view. The health routes are added with `.route` before `.leptos_routes`, so Axum matches them first; the Playwright test for `/health/nothing` confirms the fallback still handles everything else.

### What does readiness check in a template with no database?

That the server can serve the app: the `site-root` directory from `LeptosOptions` exists and contains the `pkg` directory with the compiled bundle. That is what a fresh container lacks until `cargo leptos build` has run. Each later dependency is added as another named check in `health.rs`.

### Why install nightly Rust?

The template's `rust-toolchain.toml` pins the `nightly` channel, and `cargo-leptos` expects it along with the `wasm32-unknown-unknown` target and `sass` for `style/main.scss`. The agent installs what the project asks for, so the end-to-end run is the same one a developer gets locally.

## More Leptos jobs

- [Add i18n to a Leptos App](https://getrush.ai/run/add-i18n/leptos/)
- [Add Open Graph Tags to a Leptos App](https://getrush.ai/run/add-open-graph-tags/leptos/)
- [Add Prometheus Metrics to a Leptos App](https://getrush.ai/run/add-prometheus-metrics/leptos/)

## The same job on other stacks

- [Add a Health Check Endpoint to a Litestar App](https://getrush.ai/run/add-health-checks/litestar/)
- [Add Health Checks to an Express and Mongoose API](https://getrush.ai/run/add-health-checks/mongoose/)
- [Add Health Checks to a NestJS API](https://getrush.ai/run/add-health-checks/nestjs/)

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