Local lifecycle

boson-orchestration is the private control plane behind the small CLI surface. It keeps migrations, process supervision, health gates, logs, and shutdown behavior consistent across every Boson project. Infrastructure is configured and operated independently by the developer.

Startup sequence

validate project and tools
          ↓
build migrate + Server + Worker
          ↓
connect to configured infrastructure and migrate
          ↓
start and health-gate processes
          ↓
stream logs and supervise

Server readiness has a 60-second health window. Startup exits without modifying infrastructure if building, migration, process launch, or health gating fails.

Supervision

Boson holds a per-project lifecycle lock while the stack runs. A second boson start exits with guidance to use boson status or boson logs.

The foreground supervisor checks Server and Worker every second. If either exits unexpectedly, Boson reports the failed service and points to its logs.

Graceful shutdown

Ctrl+C and boson stop follow the same shutdown path:

1. Signal Server and Worker.
2. Allow up to ten seconds for each process to exit.
3. Clear transient lifecycle state.

Infrastructure is never stopped or changed by the lifecycle supervisor.

Graceful process signaling is currently supported on macOS and Linux. Other platforms may report that graceful stop is not yet available.

State and logs

Transient lifecycle state is stored under .boson/run:

• .boson/run/state.json — supervised units, ports, and versions
• .boson/run/lifecycle.lock — exclusive lock for one boson start per project

Unified service logs are appended under .boson/logs/<unit>.log. Both directories are gitignored.

boson status
boson logs
boson logs server --follow

If a previous supervisor crashed, the next lifecycle command detects stale process state.

Troubleshooting

Symptom	What to do
Boson is already running for this project	Use boson status or boson logs; stop with boson stop
Server or Worker exited unexpectedly	Inspect boson logs server or boson logs worker
Service did not become healthy	Check that service's logs; readiness waits up to 60 seconds
Port already in use	boson doctor reports this as a warning; close the owner or stop an existing Boson stack
Required doctor check failed	Apply the printed fix: line, then retry

Infrastructure boundary

boson start consumes connection details from project configuration. It never creates PostgreSQL servers, buckets, mail providers, containers, or clusters. Optional development infrastructure remains outside Boson's lifecycle.