Description
Local Runtime Operations provide the operator controls around a self-hosted daemon: start it detached or in the foreground, stop it gracefully, inspect identity and health, run a comprehensive doctor report, export a scrubbed support bundle, back up or restore data, benchmark the runtime, migrate between local and hosted deployments, and explicitly reset local data. The client surface remains import-light so CLI commands can manage the daemon by process and HTTP boundaries without loading the server graph into every command.
Lifecycle operations distinguish a healthy Dots daemon from a foreign process on the configured port. Start adopts the matching instance or safely handles a start lock; stop confirms identity before shutdown and uses bounded process-tree termination only when graceful teardown fails. Doctor combines filesystem, lock, engine, migration, memory, disk, and log evidence into named problems.
Selling Points
- Gives self-host operators one coherent command family for normal lifecycle and troubleshooting.
- Adopts an already-running daemon instead of spawning duplicates or corrupting a shared data directory.
- Identifies foreign port occupants and stale locks, making common local failures explainable.
- Produces a support bundle and doctor report with actionable facts rather than requiring manual log archaeology.
- Keeps destructive reset explicit and scoped to canonical data directories, preserving unrelated credentials and logs.
User Story
An operator sees that Desktop cannot reach its bundled backend. They run dots local status, then dots local doctor. The report identifies whether the daemon is down, the port belongs to another process, migrations disagree, disk space is low, or the database is unhealthy. They can restart it or export a support bundle and know exactly what state was observed.
Extension Surface
This feature is automatable. packages/local-runtime/src/client/lifecycle.ts exports deterministic start, stop, status, and reset functions used by CLI surfaces, and packages/local-runtime/src/client/operability.ts exports doctor and support-bundle operations. They are fully scriptable end to end, but the command set is closed and has no external operation-registration protocol.
Capabilities & Limits
- Starts in detached or foreground mode, health-polls readiness, and adopts a matching live instance.
- Stops gracefully with identity checks and a bounded forced-stop fallback.
- Reports daemon, database, migration, disk, directory-size, memory, lock, and log-tail health.
- Exports a support bundle, manages backups, runs bounded benchmarks, and supports hosted/local migration directions.
- Limit: reset deletes the canonical database and files directories and must remain an explicit destructive action.
Implementation Map
packages/local-runtime/src/client/lifecycle.tspackages/local-runtime/src/client/operability.tspackages/local-runtime/src/daemon/control-app.tspackages/cli/src/commands/local.tspackages/cli/src/commands/local-migrate.ts