From c7a26332e832c1bfe2f2af70645acc79083e266f Mon Sep 17 00:00:00 2001 From: Anders Olsson Date: Fri, 7 Aug 2026 15:52:20 +0200 Subject: [PATCH] docs(readme): document the wait-for readiness gate --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index ccd95be..a360da7 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,28 @@ Commands: Exit codes: 0 success, 1 operational error, 2 daemon unreachable, 3 config invalid. +## Waiting on a dependency + +A server can declare a precondition that must hold before it is started: + + wait-for { + path "~/.orbstack/run/docker.sock" + timeout "180s" + interval "1s" + } + +Exactly one condition per block — `path "

"` (the path exists), +`tcp ""` (a connection succeeds), or `command ""` with optional +`args` (the process exits 0). `timeout` defaults to 120s and `interval` to 1s. + +While waiting the server reports state `waiting`, and `xy status ` shows +which condition it is blocked on and for how long. If the timeout expires the +server is marked `failed` and is never spawned. + +Waiting does **not** consume the restart budget: a slow dependency costs +patience, not retries. This is what stops a Docker-backed server from being +marked failed at login while the Docker daemon is still starting. + ## Start on login (macOS) xy service install # write the LaunchAgent, load it, start the daemon