---
title: "Ready checks"
url: https://devlanes.run/examples/basics-ready-checks/
description: "Tell devlanes when each service is up, with an http, tcp, log or cmd ready check."
---

# Ready checks

One [Hono](https://hono.dev) server run as eight services, each with another kind of `ready` check, including an app that answers only on its own hostname and one that answers only on `127.0.0.1:<port>`. The `MODE` variable picks each service's behaviour, so `devlanes.yaml` is the file to read.

## Requirements

- devlanes, with `devlanes setup` run once
- Node 22 or later
- curl on `PATH`, for the `ready.cmd` check of `own-host-cmd`

## Run it

```sh
cd basics-ready-checks
devlanes start
```

`devlanes start --no-ui` prints the start as text:

```text
example-ready-checks@0 · main
✓ services  8 of 8 ready
  ✓  index         https://example-ready-checks.localhost
  ✓  http-check    https://http-check.example-ready-checks.localhost
  ✓  tcp-check     https://tcp-check.example-ready-checks.localhost
  ✓  log-check     https://log-check.example-ready-checks.localhost
  ✓  own-host      https://own-host.example-ready-checks.localhost
  ✓  own-host-cmd  https://own-host-cmd.example-ready-checks.localhost
  ✓  legacy-host   https://legacy-host.example-ready-checks.localhost
  ✓  slow-start    https://slow-start.example-ready-checks.localhost
```

Open https://example-ready-checks.localhost. The page shows lane 0 of `example-ready-checks` and links to every service with the check it uses. Each service's page shows the `Host` header the app received: `own-host.example-ready-checks.localhost` on own-host, `127.0.0.1:<port>` on legacy-host.

## During a start

The first start of a lane runs the `install` task (`npm install`), because a new worktree has no `node_modules`. Then devlanes starts every service with `npm run dev` from `package.json` (the `node` template), sets `MODE` from the service's `env`, and waits for each one's check:

- `index` at `example-ready-checks.localhost`: `ready.http` on `/healthz`. Its links come from `services.<name>.public_url`.
- `http-check`: `GET /healthz` on its port must answer 2xx within 15 s.
- `tcp-check`: ready as soon as its port accepts a connection, whatever the app would answer.
- `log-check`: waits 3 s, then listens and prints `log-check listening on http://127.0.0.1:<port>`, which `ready.log` matches.
- `own-host`: answers 400 to any `Host` but `own-host.example-ready-checks.localhost` (`ALLOWED_HOST`), the way Django's `ALLOWED_HOSTS` does. The check sends `Host: 127.0.0.1:<port>` by default, so `ready.http.host` sends `${{ self.hosts[0] }}` instead.
- `own-host-cmd`: the same app, checked by `ready.cmd` with `curl -fsS -H "Host: ..." http://127.0.0.1:<port>/healthz`.
- `legacy-host`: answers 400 to any `Host` but `127.0.0.1:<port>`. `host_header: upstream` makes the proxy send that address instead of the hostname, and the check sends it by default.
- `slow-start`: sleeps 8 s before it listens, so it shows `starting` in `devlanes status` until then.

## Try next

On Windows, add `--ssl-revoke-best-effort` to the `curl` commands.

- Start a second lane: `git worktree add ../examples-checkout -b feat/checkout`, then `cd ../examples-checkout/basics-ready-checks && devlanes start`. The new worktree is lane 1 at https://example-ready-checks1.localhost, with `http-check.example-ready-checks1.localhost` and the rest, and `curl https://example-ready-checks1.localhost/lane` answers `"lane":1`. `devlanes lane new --name example-ready-checks-review --start` in this folder gives the same lane 1 without a worktree.
- Catch a service while it starts: `devlanes restart slow-start --no-ui --timeout 2s` stops waiting after 2 seconds and exits 124:

  ```text
  example-ready-checks@0 · main
  ✗ services  0 of 1 ready
    starting  slow-start
  ! timed out before every unit was ready
  ```

- Right after that, `devlanes debug why slow-start` prints `starting; waiting for its readiness check (devlanes wait example-ready-checks@0:slow-start)`.
- `devlanes wait slow-start` returns `ready example-ready-checks@0:slow-start` once the server listens.
- Break a check: change http-check's `path: /healthz` to `path: /missing` in `devlanes.yaml` and run `devlanes reload --no-ui`. After the 15 s timeout it exits 1:

  ```text
  example-ready-checks@0 · main
  ✗ services  0 of 1 ready
    ✗  http-check  wasn't ready in time; GET /missing (Host: 127.0.0.1:20520) answered 404   http-check listening on http://127.0.0.1:20520

  hint: use a `ready.http.path` that answers 2xx, set `ready.http.host` if the app routes by hostname, or set `ready.http.status: 404`
  ```

  The process keeps running, but https://http-check.example-ready-checks.localhost now gets the proxy's `DL203 Service failed` page (503), and `devlanes debug why http-check` prints the same reason. Put `/healthz` back and `devlanes reload --no-ui` brings it back to ready.

- Drop the Host rewrite: delete `host_header: upstream` from legacy-host and save. The proxy applies the route change by itself (`devlanes reload` reports `nothing to reload`), and `curl https://legacy-host.example-ready-checks.localhost/` answers 400 with `invalid host legacy-host.example-ready-checks.localhost: this app answers only on 127.0.0.1:<port>`. Put the line back.
- `devlanes lane clean 0 --yes` stops lane 0 and deletes its data and logs. Run it with `1` for the second lane.

## Files

- [`devlanes.yaml`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/basics-ready-checks/devlanes.yaml): the `install` task and the eight services with their `MODE` and ready check, with a comment wherever a key is the point.
- [`src/modes/`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/basics-ready-checks/src/modes): one file per behaviour. `log.ts` and `slow-start.ts` delay the listen, `own-host.ts` and `legacy-host.ts` refuse other `Host` headers.
- [`src/index.ts`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/basics-ready-checks/src/index.ts): picks the mode from `MODE` and starts the server.
- [`src/host-guard.ts`](https://github.com/devlanes-run/examples/blob/d2a99f076179db99581cef85453a58b788f3970b/basics-ready-checks/src/host-guard.ts): the middleware that answers 400 to another `Host`.

## Docs

- [Service patterns: frontend and API](/docs/guides/services/#frontend-and-api), on the `http` check, its `host` and `User-Agent: devlanes-ready`
- [Config reference: services](/docs/reference/config/#services), every `ready` and `hosts` key
- [Lane lifecycle: editing the project file](/docs/guides/lifecycle/#editing-the-project-file), on `devlanes reload`
