What the agent does
The agent reads the app as it is. In a project shaped like the node-custom-server template in remix-run/react-router-templates it finds a package.json with react-router and @react-router/express on the current major, express 5.2, compression and morgan, React 19.2 and Vite 8, and four scripts: build runs react-router build, dev runs server.js with NODE_ENV=development, start runs the same file in production, and typecheck runs react-router typegen && tsc -b. It reads server.js, where an Express app mounts compression, disables x-powered-by, and in development loads server/app.ts through Vite's ssrLoadModule while in production serves build/client and imports build/server/index.js. It reads server/app.ts, where createRequestHandler from @react-router/express catches every request and hands it to the React Router build with a RouterContextProvider that sets the value from app/context.ts.
That is the whole problem: every path, including /health, currently reaches the React Router handler, which renders the root route's ErrorBoundary as a 404 page for anything app/routes.ts does not list, with a full HTML document a load balancer cannot read cheaply. So the agent adds the health route to server.js, before the development and production branches, as app.get("/health", ...) answering { "status": "ok", "uptime": process.uptime() } with Cache-Control: no-store. It goes ahead of express.static and ahead of the request handler in both branches, so neither the static middleware nor the SSR handler ever sees it, and it needs no React Router route, no loader and no change to app/routes.ts.
A readiness variant belongs in the same file only if the app has something to be ready for. This template has no database, so the agent adds a single /health and leaves a comment where a /health/ready would check a pool. If resources names a repository whose server.js already opens a database client, the agent reads that and adds the readiness route against it, which is why it reads the server file before deciding.
The repository has no unit tests of its own; its .tests workspace runs Playwright against each template in CI. So the agent proves the route the way the template is already proved: npm run build, then npm run start in the sandbox, then curl -i http://localhost:3000/health to show a 200 with the JSON body, and curl -i http://localhost:3000/does-not-exist to show the SSR 404 is still the React Router one. It also builds the Dockerfile, which copies server.js into the final node:24-alpine stage, and adds a HEALTHCHECK line to that stage that polls the new route, so an orchestrator that reads container health gets it for free. Then it runs npm run typecheck and opens a 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 to this React Router app's custom Express server. In server.js add GET /health that answers 200 with a small JSON body and Cache-Control: no-store, registered before the static middleware and before the React Router request handler in both the development and production branches so it never reaches SSR. Do not add a React Router route for it. Add a HEALTHCHECK to the final stage of the Dockerfile that polls the route. Build the app, start it, show curl output for /health and for an unknown path, run npm run typecheck, and 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 on its own branch. The diff touches server.js, where the route is a few lines above the if (DEVELOPMENT) branch, and the Dockerfile, where the last stage gains a HEALTHCHECK that uses wget or node -e to poll /health, whichever the node:24-alpine image can run without adding a package. app/routes.ts, app/root.tsx and server/app.ts are untouched. The description pastes the two curl responses so a reviewer sees the JSON on /health and the HTML 404 on an unknown path side by side.
The proof is in the trajectory at GET /o/{org}/sessions/{id}/messages: every npm run build, the npm run start that served the route, the curl calls with their full responses, the docker build and the npm run typecheck. The changed files with their diffs are at GET /o/{org}/p/{project}/sessions/{id}/changes, so a reviewer can read the two files without checking the branch out. The repository's Playwright workflow in .github/workflows/ci.yml runs on the pull request as it does on every push.
Before merging, a reviewer checks that the route sits above express.static in the production branch, so a file named health in build/client could never shadow it; that it sits above the Vite middleware in the development branch, so npm run dev answers it too; and that the HEALTHCHECK interval and timeout fit the platform the container runs on. The sandbox pushes one branch and nothing else.
Run it on every new React Router service
A team that runs several React Router apps on custom Express servers starts one run per repository with POST /o/{org}/sessions, this prompt and that repository in resources. Each run reads its own server.js, so an app that already opens a database in that file gets a readiness check against it and an app that only serves the build gets the plain liveness route, and each opens its own pull request. Send a request_id per run so a retry returns the run already started.
Set a webhook_url on the API key and every run the key starts posts run.completed or run.failed when it finishes, with a session_url for the result, so a script can collect the pull request links for review together. The key runs at most max_concurrent sessions at once, 4 by default; past that, a new session still answers 202, with status: "queued", and starts when a slot frees.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The route is three lines, and the mistakes are all about where the three lines go: below the static middleware, below the SSR handler, or in a React Router route that renders a document. Proving the placement means building the app, starting the production server and watching what /health and a wrong path each return, and then building the Docker image to see the HEALTHCHECK work. On Rush the run has its own sandbox with a computer in it, so the agent does all of that without touching your checkout or your Docker daemon.
The result is a pull request with the evidence attached rather than a note that it works: the curl output is in the trajectory and the description, the image built in the sandbox, and the diff is small enough to read in a minute. Several services mean several sandboxes and several pull requests at once.
Frequently asked questions
Why not add /health as a React Router route with a loader?
A route module would render through the SSR handler, carry the root Layout and ErrorBoundary, and cost a React render per probe. A route on the Express app answers before React Router is involved, with no HTML, which is what a load balancer or a container runtime wants. The template's server/app.ts is left alone.
Does it work in development as well as production?
Yes. server.js has two branches, one that mounts Vite's middleware and one that serves build/client, and the route is registered before both, so npm run dev on port 3000 and npm run start answer it the same way. The trajectory shows the production path; the development path is the same app.get.
Will the Dockerfile change pull in another package?
No. The final stage is node:24-alpine, which has wget from BusyBox and node itself, so the HEALTHCHECK uses one of those. The agent runs docker build in the sandbox to prove the stage still builds, and the image is never pushed anywhere.
What about a readiness check for my database?
The template has no database, so the page adds liveness only. If your server.js opens a pool, say so in the prompt or let the agent find it; it adds /health/ready that runs a trivial query and answers 503 when the pool cannot hand out a connection, and shows that path in the same curl output.
Does this change the 404 behaviour for real pages?
No. An unknown path still reaches the React Router handler and renders the root ErrorBoundary from app/root.tsx with its 404 message. The agent includes a curl of an unknown path in the pull request so a reviewer sees that nothing else moved.