Foreman
Keeps toryo's background services running. Foreman is the supervisor: it knows which long-running services should be up, probes whether they are, starts what is down, and, in daemon mode, restarts anything that goes red.
It is deliberately not a dashboard or a metrics collector. Its report is binary per service: green or red.
What it supervises#
| Service | What it is |
|---|---|
postgres | the local database every knowledge and queue app stores into, either Docker or the embedded pglite runtime |
dispatch | the job queue daemon that spawns workers |
messaging | the notification spine behind board's inbox |
scheduler | the time-based trigger daemon |
sequence | the multi-step orchestrator daemon |
relay | the live-worker control plane and stall detector |
ollama | the local model host used for embeddings and the memory judge |
Dependencies are respected in both directions. Bringing one service up brings up what it depends on first; taking one down takes its dependents with it, because their open connections are about to go stale.
toryo setup installs foreman's watch daemon for you, as a launchd agent.
In normal use you never start it by hand.
Checking on it#
toryo foreman check is the health report: green or red per service, exiting
non-zero if anything is down. Each entry carries the time that service started,
which is how you tell "green since this morning" from "green since twenty
seconds ago", the tell that something is crash-looping and being quietly
restarted.
toryo doctor answers a different question. Where check reports on services
foreman can start, doctor reports on host prerequisites it cannot: is bun
new enough, is Docker installed and running, are git / tmux / claude on
your PATH, is ~/.toryo writable, does the database config resolve and
connect, are the local models pulled, is your license valid. Every failing item
comes with a fix hint.
Failures are graded. Missing bun, Docker, tmux, claude, or git fails the
report. Missing gh or an unstarted Ollama only warns, since toryo runs without
them; you just lose pull-request handling or knowledge enrichment until they
are there.
Run doctor first whenever something is behaving strangely. It is the fastest
way to find out whether the problem is toryo or the machine underneath it.
Statelessness#
Foreman keeps no database and no PID files. Each service's own liveness
mechanism is the source of truth, so foreman check works even when everything
else is down. It depends on nothing it supervises.
Where things go wrong#
- A service flaps green then red. Check its start time in
foreman check; a time that keeps resetting meanswatchis restarting it every few seconds. Service logs are under~/.toryo/foreman/logs/. - Everything is red. Almost always
postgres. Runtoryo doctor, since a stopped Docker daemon takes the whole stack with it. watchwill not start. Only one may run at a time; a second exits with a lock-contention code rather than fighting the first.
Full command surface: CLI & contract reference.