up: make it run, and wait for real

up starts what the manifest declares, in dependency order. --wait returns only when the selected services actually listen and pass their health checks.

Start in dependency order

Services start in the order of depends_on. A service with prepare: runs that prerequisite first, in the same working directory, and only starts its long-running cmd: on success. Services already running are skipped; each service keeps its own log file and run record.

oberth up --wait

api      started   :21730   ready
worker   started   no port

What --wait proves

Without --wait, up has started processes; it has not proved they are usable. With --wait, a service with a port must listen; a service that declares health: must also pass that check; a portless worker is ready when its run record becomes active. Services that were already running are included in the wait.

Each service waits by its own ready_timeout: (default 30s). --wait-timeout is an overall ceiling that only tightens the per-service budgets.
prepare: does not count against the readiness budget; slow installs need prepare_inputs: caching or a larger script timeout on the caller's side.
Without waiting, a started service carries ready: false and the table says readiness was not confirmed. That is not a failure.
A service that times out is failed with reason ready_timeout; the message says whether the service's own budget or the caller's ceiling expired first.

When it fails

Each entry in services[] is started, skipped or failed; a failure carries a branchable reason and a hint that points at evidence that really exists. A partial success is still exactly one JSON value, with exit code 1.

Start failure reasons
Reason	What happened	What to read first
`start_failed`	The command never started.	The hint: the executable, working directory or environment that refused it.
`port_occupied`	The fixed port was already taken.	`port_holder`: the port, pid, command and kind of the holder.
`dependency_not_ready`	A dependency exited during the wait.	The dependency's logs; the message carries its exit code and reason.
`dependency_timeout`	A dependency stayed alive but never became ready.	The dependency's own `ready_timeout:` and logs.
`ready_timeout`	The service itself did not become ready in budget.	The service's logs and its readiness declaration.

Restart without losing the address

restart stops the project and starts it again. With --only it restarts just the named services while the rest keep running, and it preserves the worktree's port: auto reservation, so a service gets its original address back. restart does not wait for readiness; use up --wait when the caller needs proof.

keep the address

oberth restart --only api

Boundaries

Edit this page