# Add Health Checks to an AdonisJS API

Yes. An agent adds /health/live and /health/ready to your AdonisJS API with the core health checks module, a Lucid DbCheck and a secret header, with tests and a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-health-checks/adonisjs/). 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 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`

```json
{
  "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"
    }
  ]
}
```

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 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.

## 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.

## More AdonisJS jobs

- [Add i18n to an AdonisJS App](https://getrush.ai/run/add-i18n/adonisjs/)
- [Add Password Reset to an AdonisJS App](https://getrush.ai/run/add-password-reset/adonisjs/)
- [Add Rate Limiting to an AdonisJS API](https://getrush.ai/run/add-rate-limiting/adonisjs/)

## The same job on other stacks

- [Add Health Checks to an aiohttp App](https://getrush.ai/run/add-health-checks/aiohttp/)
- [Add Health Checks to an ASP.NET Core App from a Linear Issue](https://getrush.ai/run/add-health-checks/aspnet-core/)
- [Add Health Checks to an Axum Service](https://getrush.ai/run/add-health-checks/axum/)

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