What the agent does
The agent reads how the API is wired before it adds a probe, because in AdonisJS a route is only reachable through the middleware stacks in the kernel. In the api kit of adonisjs/starter-kits, package.json is on @adonisjs/core ^7.5.2 with @adonisjs/lucid ^22.4.2, @adonisjs/auth, @adonisjs/cors, @adonisjs/shield, @adonisjs/session and better-sqlite3, and tests run on Japa with @japa/api-client. start/routes.ts answers / with { hello: 'world' } and puts auth/signup, auth/login, account/profile and account/logout under an /api/v1 group, the last two behind middleware.auth(). Every handler is referenced as controllers.Profile from #generated/controllers, a file under .adonisjs/server/ that the indexEntities hook in adonisrc.ts regenerates. start/kernel.ts runs force_json_response_middleware, container_bindings_middleware and CORS on every request, then the body parser, session, Shield, initialize_auth_middleware and silent_auth_middleware on routed ones. config/database.ts uses the sqlite connection through better-sqlite3 at app.tmpPath('db.sqlite3'), with commented-out pg, mysql, mssql and libsql blocks. The kit's README.md lists a health check endpoint among its features, but no route, controller or start/health.ts exists in the tree.
The health checks module ships in @adonisjs/core, so no package is added. The agent runs node ace configure health_checks, the command the AdonisJS guide gives, which creates start/health.ts exporting a HealthChecks instance that registers DiskSpaceCheck and MemoryHeapCheck from @adonisjs/core/health, and app/controllers/health_checks_controller.ts with a live method returning response.ok() and a ready method that awaits healthChecks.run() and answers response.ok(report) when report.isHealthy is true and response.serviceUnavailable(report) otherwise. If the installed core version lacks that configure command, the agent writes the same two files by hand. Because the kit ships Lucid, it adds new DbCheck(db.connection()) from @adonisjs/lucid/database, so readiness fails when the configured connection cannot answer, and the report names the connection it tested. The default thresholds stay: disk warns at 75% and fails at 80%, heap warns at 250 MB and fails at 300 MB. The pull request says where warnWhenExceeds and failWhenExceeds go when the container's memory limit is lower than that.
The two routes go into start/routes.ts outside the /api/v1 group and without middleware.auth(), because a probe from Kubernetes or a load balancer carries no access token: router.get('/health/live', [controllers.HealthChecks, 'live']) and the same for /health/ready. The readiness report includes debugInfo with the process id, platform, uptime and Node version, so the agent follows the guide and guards /health/ready with a route middleware that compares request.header('x-monitoring-secret') with a value from the environment and answers response.unauthorized() otherwise. Rather than the literal secret in the guide, it adds MONITORING_SECRET to the schema in start/env.ts and to .env.example and .env.test, since Env.create refuses to boot when a declared variable is missing. .adonisjs/server/controllers.ts is regenerated so controllers.HealthChecks resolves, and the generated file is committed as the kit already commits it.
The test is tests/functional/health.spec.ts, in the functional suite that adonisrc.ts defines and tests/bootstrap.ts starts an HTTP server for. It calls client.get('/health/live') and asserts 200; calls /health/ready with no header and asserts 401; calls it with the header and asserts 200, isHealthy true and a checks entry whose name ends in the connection name from config/database.ts. A fourth case registers a check that always fails against a second HealthChecks instance and asserts the 503 shape, so the unhealthy branch is covered without breaking the database. In its sandbox the agent copies .env.example to .env, runs node ace migration:run, then npm run typecheck, npm run lint and npm run test, and starts the server with npm run dev to curl both routes and paste the JSON report 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 liveness and readiness health checks to this AdonisJS API. Read package.json, adonisrc.ts, start/routes.ts, start/kernel.ts, start/env.ts, config/database.ts, .env.example, .env.test, tests/bootstrap.ts and the existing controllers first. Use the health checks module from @adonisjs/core: run node ace configure health_checks, or write start/health.ts and app/controllers/health_checks_controller.ts by hand with the same shape if the command is unavailable. Register DiskSpaceCheck, MemoryHeapCheck and a Lucid DbCheck for the configured connection. Add GET /health/live and GET /health/ready in start/routes.ts outside the /api/v1 group and without the auth middleware; guard /health/ready with a route middleware that requires an x-monitoring-secret header matching a MONITORING_SECRET environment variable declared in start/env.ts and added to .env.example and .env.test. Make sure the generated controllers registry includes the new controller. Write tests/functional/health.spec.ts covering 200 on live, 401 and 200 on ready, the report shape, and a failing check returning 503. Run the migrations, typecheck, lint and the test suite, start the server and curl both routes, and open a pull request with the readiness report in its description.",
"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 that adds start/health.ts, app/controllers/health_checks_controller.ts and tests/functional/health.spec.ts, changes start/routes.ts, start/env.ts, .env.example and .env.test, and updates the generated .adonisjs/server/controllers.ts. The description shows one GET /health/ready response as the sandbox saw it, with isHealthy, status, finishedAt, debugInfo and the three checks, each with its name, status, message and meta, and the output of npm run test with the four new cases.
The run's record holds every command: the configure step, the migration, typecheck, lint and tests, and the two curls, so a reviewer can see the 401 without the header and the 200 with it rather than take the description's word for it.
Before merging, a reviewer decides whether debugInfo should be exposed at all behind the secret, whether readiness should also check the session store once SESSION_DRIVER moves off cookie, and what memory thresholds match the container the API will run in. The probe paths are the ones to put in the deployment's livenessProbe and readinessProbe, with the header on the readiness one.
Run it on every new AdonisJS service
A team that starts services from the same kit 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 a second pull request. Each run reads that service's own config/database.ts and registers a DbCheck for the connection it finds.
After that, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request adds a connection to config/database.ts or a new infrastructure dependency, check that start/health.ts registers a check for it and comment with what is missing" keeps the readiness report honest as the service grows. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A health endpoint is small, but the mistakes around it are not: a readiness route behind the auth middleware that every probe fails, a liveness check that pings the database and turns an outage into a restart loop, or a report that prints the Node version to anyone who asks. The agent reads the kernel and the routes file first, so the probes land outside /api/v1 and the auth middleware, and the report sits behind a header the deployment sends.
Running it on Rush means the migrations, the test suite and the two curls happen in the run's own sandbox with their output kept, so the pull request carries proof instead of a promise. A team with several AdonisJS services starts one run per repository and reviews each pull request on its own.
Frequently asked questions
Why two endpoints instead of one /health?
Because an orchestrator treats them differently. A failing liveness probe restarts the container, so /health/live must not depend on the database or anything else that can be down for reasons a restart will not fix. A failing readiness probe only takes the instance out of the load balancer, so /health/ready is where the DbCheck belongs.
Does the readiness endpoint leak anything?
The report carries debugInfo with the process id, platform, uptime and Node version, plus disk and heap numbers. That is why the agent guards /health/ready with an x-monitoring-secret header read from MONITORING_SECRET and answers 401 without it. Kubernetes probes and most monitors can send a custom header, and the pull request shows the httpHeaders block for a readiness probe.
Will the checks slow the API down?
Each probe runs the registered checks on request, and the disk check reads the file system. For a probe interval of a few seconds the cost is small; for a check that is expensive, the module's cacheFor method keeps the last result for a duration you set and marks it isCached in the report. The agent leaves caching off and notes where to add it.
What about Redis or a Postgres connection count?
The @adonisjs/redis package provides RedisCheck and RedisMemoryUsageCheck, and Lucid provides DbConnectionCountCheck for PostgreSQL and MySQL. The kit uses SQLite and no Redis, so the agent registers the checks that match what is configured and lists the others in the pull request for when the service gains those dependencies.