# Add Health Check Endpoints to a Hono API

Yes. An agent adds liveness and readiness routes to your Hono Worker that probe the KV binding, writes Workers vitest tests for both, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-health-checks/hono/). 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 app is wired before it adds a route, because a health check must sit outside the authentication and prefixing the app already applies. In an API shaped like the `blog` example in honojs/examples, `package.json` depends on `hono ^4.2.4` with `wrangler ^3.53.0`, `vitest 1.3.0` and `@cloudflare/vitest-pool-workers ^0.2.0` as dev dependencies, and its scripts are `wrangler dev src/index.ts`, `wrangler deploy src/index.ts` and `vitest --run`. `src/index.ts` creates the app, answers `/` with plain text, sets a JSON `notFound`, applies `prettyJSON()` and a `basicAuth` guard to every non-GET under `/posts/*`, and mounts `src/api.ts` under `/api`. `src/bindings.ts` declares `USERNAME`, `PASSWORD` and the `BLOG_EXAMPLE` KV namespace; `src/model.ts` stores each post under a `v1:post:` prefix with `KV.list`, `KV.get`, `KV.put` and `KV.delete`.

There is one dependency a readiness probe should cover here, the KV namespace, and nothing else: no database, no upstream API. The agent adds `src/health.ts` with a small Hono sub-app and two routes. `GET /health` is liveness and returns `{ ok: true }` with `Cache-Control: no-store`, nothing more, because a liveness probe that touches storage turns a storage blip into a restart. `GET /health/ready` performs one `KV.get` on a key that never exists, `v1:health`, inside a `Promise.race` with a short timeout, and answers `{ ok: true, checks: { kv: "ok" } }` or, on an exception or timeout, status 503 with `checks.kv` set to the error message. The sub-app is mounted at the root in `src/index.ts`, outside `/api`, so `prettyJSON` and the basic-auth middleware never run for it and a monitor needs no credentials.

The existing tests show how to exercise the Worker: `src/api.test.ts` imports `env` from `cloudflare:test` and calls `worker.request('/posts', {}, env)` against a real KV in the Workers pool, with `vitest.config.ts` pointing at `./wrangler.toml` and `isolatedStorage: false`. The agent adds `src/health.test.ts` in the same style: `/health` returns 200 and `{ ok: true }`, `/health/ready` returns 200 with `kv: "ok"` against the test namespace, and a third case passes a stub env whose `BLOG_EXAMPLE.get` rejects and asserts 503 and the error text. It also asserts that `/health` carries `Cache-Control: no-store`.

To run anything, the agent copies `wrangler.example.toml` to `wrangler.toml` in the sandbox as the README instructs, since the vitest pool reads the KV binding from it; it commits no copy of that file. It runs `npm install` at the workspace root, `npm test -w blog`, and `npx tsc --noEmit -p blog`, then starts `wrangler dev` and `curl`s both routes, pasting the responses and the test summary in the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add health check endpoints to this Hono Worker and open a pull request. Read package.json, wrangler.example.toml, vitest.config.ts, tsconfig.json, src/index.ts, src/api.ts, src/model.ts, src/bindings.ts and src/api.test.ts first. Add src/health.ts with a Hono sub-app: GET /health returns { ok: true } with Cache-Control: no-store and touches no storage; GET /health/ready does one KV.get on the key v1:health against the BLOG_EXAMPLE binding under a short timeout and returns { ok: true, checks: { kv: 'ok' } }, or 503 with the error message on failure or timeout. Mount it at the root in src/index.ts, outside /api and outside the basic-auth middleware. Add src/health.test.ts in the style of src/api.test.ts using env from cloudflare:test, covering both routes, the no-store header and a stubbed failing KV. Copy wrangler.example.toml to wrangler.toml in the sandbox only. Run npm install, npm test for this workspace and a TypeScript check, start wrangler dev, curl both routes and paste the responses and test summary in the pull request. Do not change the existing routes or the auth middleware.",
  "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 with two new files, `src/health.ts` and `src/health.test.ts`, and two lines in `src/index.ts`: the import and the `app.route('/', health)` mount. The description shows `curl -i` output for `/health` and `/health/ready` from `wrangler dev`, including the `Cache-Control: no-store` header, and the vitest summary with the three new cases.

The repository has no CI workflow of its own, only Dependabot, so the pasted test run and the agent's `tsc` check are the evidence until the team adds one. A reviewer who wants the check on every pull request can take the single command, `npm test -w blog`, into a workflow.

A reviewer checks that `/health` does not call KV, that `/health/ready` returns 503 and not 200 on a failed probe, that the probe key is under the same `v1:` prefix convention as posts so it never collides with one, and that the routes are mounted before `/api` and not behind `basicAuth`. Then they point their uptime monitor or load balancer at `/health/ready`.

## Run it on every service added to a monitor

A platform team that wants the same two routes on every Worker sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own bindings file, so a Worker with a D1 or R2 binding gets a readiness probe for that instead of KV, and each opens its own pull request on its own branch.

Send a `request_id` with each body so a retry returns the run already started. With a `webhook_url` on the API key, Rush POSTs `run.completed` when each turn ends, with the `session_url` to read the pull request from, so the monitor configuration and the code change can be reviewed together.

## Why run it on Rush?

A health check is small, and the mistakes are small too: a probe that sits behind auth, a liveness route that depends on storage, a 200 that should have been a 503. They show only when the Worker actually runs, and in a Rush sandbox it does. The agent runs the Workers vitest pool and `wrangler dev`, and every command and response is kept in the run's record, so a reviewer sees the real headers rather than reading the intent off a diff.

The same request body works unchanged on every Hono service a team runs, and runs for several repositories proceed at once in their own sandboxes. Each pull request carries its own test output, so the person adding services to a monitor reviews evidence rather than reruns tests by hand.

## Frequently asked questions

### Why two routes instead of one?

A liveness check answers whether the Worker can serve a request at all; a readiness check answers whether its dependencies are reachable. Combining them makes a KV outage look like a dead service. `/health` touches nothing and `/health/ready` probes `BLOG_EXAMPLE`, so each signal means one thing.

### Will it be behind the basic auth?

No. In `src/index.ts` the `basicAuth` middleware applies only to non-GET requests under `/api/posts/*`, and the health sub-app is mounted at the root, outside `/api` altogether. A monitor calls both routes with no credentials.

### Does the readiness probe write to KV?

No. It calls `KV.get` on `v1:health`, a key nothing ever writes, so it exercises the binding and the namespace without consuming a write or leaving data behind. The result is a miss, which is fine; only an exception or a timeout fails the probe.

### How do the tests talk to KV?

The same way `src/api.test.ts` does: `@cloudflare/vitest-pool-workers` reads the `kv_namespaces` binding from `wrangler.toml` and gives each test a real namespace through `env` from `cloudflare:test`. The failure case uses a stub env whose `get` rejects, so no real outage is needed to cover the 503 branch.

## More Hono jobs

- [Add Input Validation to a Hono API](https://getrush.ai/run/add-input-validation/hono/)
- [Add JWT Auth to a Hono API from a Linear Issue](https://getrush.ai/run/add-jwt-auth/hono/)
- [Add OpenAPI Docs to a Hono API](https://getrush.ai/run/add-openapi-docs/hono/)

## The same job on other stacks

- [Add Health Check Endpoints to a Koa API](https://getrush.ai/run/add-health-checks/koa/)
- [Add Health Check Endpoints to a Ktor Server](https://getrush.ai/run/add-health-checks/ktor/)
- [Add Liveness and Readiness Probes to Kustomize Manifests](https://getrush.ai/run/add-health-checks/kustomize/)

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