container_wait
Block execution until a Docker container reaches a specified state: stopped, healthy, or matching a log pattern. Returns status without raising on timeout.
Instructions
Block until a container reaches a condition: stopped, "healthy", or its logs contain a pattern.
One contract for every mode: never raises on timeout — the result always carries met (condition
reached) and timed_out. The stop conditions ("not-running"/"next-exit"/"removed") use the
daemon's blocking wait and fill status_code/error (the container's exit info); "healthy" polls
the container's HEALTHCHECK every poll_intervals and fills health/status; "log-match" polls
recent logs every poll_intervals for pattern and fills matched_line. For a compose
project use compose_wait; for swarm services use service_wait.
Health semantics: with no HEALTHCHECK defined, once the container is running the tool returns
promptly with health: null and met: false (false = "not confirmed healthy", not "unhealthy" —
check health to tell them apart). A container that exits before becoming healthy returns its
terminal status and met: false.
Log-match semantics: pattern is matched as a plain substring by default — safe against any
input, including adversarial ones. Pass regex=True to match pattern as a regular expression
(via re.search) instead; only do this with patterns you trust, since a regex with catastrophic
backtracking run against attacker-influenced log content can exhaust CPU (ReDoS). Checks stdout
and stderr, most recent lines first within each poll. If the container exits/dies before the
pattern ever appears, returns promptly with met=false (not timed_out) — no further logs can
arrive, so there's nothing to keep polling for.
args:
id_or_name - The container id or name
until - Condition to wait for: "not-running" (default), "next-exit", "removed", "healthy",
or "log-match" (requires pattern)
timeout_seconds - Max seconds to wait before returning with timed_out=true (default 600)
poll_interval - "healthy"/"log-match" only: seconds between re-checks (default 2, > 0);
capped by the time left so a large value can't push the total wait past the
timeout
pattern - "log-match" only: substring (or, with regex=True, a regular expression) to look
for in the container's logs
regex - "log-match" only: treat pattern as a regular expression instead of a plain substring
returns: dict - {"container", "until", "met", "timed_out", "status_code", "error", "health",
"status", "matched_line", "waited_seconds"}; stop modes fill status_code/error,
"healthy" fills health ("starting"/"healthy"/"unhealthy", or null with no
healthcheck) and status, "log-match" fills matched_line when met and status if
the container exited without matching.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| regex | No | ||
| until | No | not-running | |
| pattern | No | ||
| id_or_name | Yes | ||
| poll_interval | No | ||
| timeout_seconds | No |