---
title: "Declare a health check in the image · Agent Wranglers"
url: https://agentwranglers.se/playbook/operations/containers/container-health
updated: 2026-10-20
licence: "All rights reserved"
---

# Declare a health check in the image

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Containers](https://agentwranglers.se/playbook/operations/containers)
- Rule: Give every service image a `HEALTHCHECK` that calls the app's own [health address](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/health-check-and-rollback).
- How: Decide which check it calls, as [separate alive from ready](https://agentwranglers.se/playbook/operations/running-the-service/liveness-and-readiness) explains. Plain Docker only marks a container `unhealthy`, so the readiness check is safe there. Docker Swarm and some platforms replace unhealthy containers, so point it at the trivial liveness check there, or a slow database causes a restart loop. Use a one-line script in the app's language, which also works in distroless images without `wget` or `curl`. Set an interval and a start period that suit the app. Orchestrators such as Kubernetes ignore it and use their own probes, so define those there too.
- Check: Once the start period has passed, `docker inspect --format '{{.State.Health.Status}}' web` prints `healthy`. With a readiness check, stopping the database turns it `unhealthy`. With a liveness check, it stays `healthy`.

Example:

```dockerfile
# Node image
HEALTHCHECK --interval=30s --start-period=10s CMD ["node", "-e", "fetch('http://localhost:8080/healthz').then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
```

```dockerfile
# Python image
HEALTHCHECK --interval=30s --start-period=10s CMD ["python", "-c", "import urllib.request, sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8080/healthz', timeout=3).status == 200 else 1)"]
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers operations playbook: https://agentwranglers.se/playbook/operations/containers/container-health`.

- Previous: [Make the container file system read-only](https://agentwranglers.se/playbook/operations/containers/read-only-containers)
- Next: [Scan every image before it ships](https://agentwranglers.se/playbook/operations/containers/image-scanning)
- [Containers](https://agentwranglers.se/playbook/operations/containers)