Description
The local daemon is a complete self-hosted Dots deployment that runs on one machine. It serves the real authenticated @dots/api, composes the same application services used by hosted Dots, stores files on local disk, and uses a managed PostgreSQL 18 database with pgvector. It can run from the CLI as a standalone daemon or as the embedded backend selected by Dots Desktop.
Boot initializes or reopens the local database, applies the filename-keyed migration ledger, composes feature services, and exposes the API on loopback. A PostgreSQL supervisor starts through pg_ctl, provisions authenticated roles, health-polls readiness, restarts isolated crashes with bounded backoff, and shuts down cleanly with the daemon.
Selling Points
- Keeps the Dots data plane on the user’s machine while retaining the full product API and account model.
- Uses real PostgreSQL and pgvector, avoiding a reduced “offline viewer” mode with incompatible behavior.
- Works both headlessly and as a Desktop-bundled instance, so the same local data supports shell and automation workflows.
- Supervises database startup, health, crash recovery, and shutdown instead of making the operator manage a separate server.
- Preserves migration history and refuses ledger divergence, protecting local work from silent schema corruption.
User Story
A consultant needs Dots on a disconnected client laptop. They select the bundled backend in Desktop, sign up as the first owner, and use normal Dotabases, search, files, and agent surfaces against localhost. The same workspace is also reachable through the installed CLI. They leave with a full Dots instance whose database and files remain under their machine’s local home.
Extension Surface
This feature is configurable. packages/local-runtime/src/config.ts and packages/local-runtime/src/paths.ts resolve supported settings such as local home and ports, while packages/local-runtime/src/daemon/boot.ts accepts explicit boot seams. Operators can change deployment behavior and provider inputs without modifying core. Formal plugin registration is cataloged separately under Plugin Development Hot Reload.
Capabilities & Limits
- Serves the full authenticated API with locally provisioned owner, company, jobs, search, and storage composition.
- Supervises bundled PostgreSQL 18 plus pgvector and preserves a durable migration ledger.
- Supports CLI foreground/detached operation and Desktop embedded operation over the same local home.
- Limit: the listener binds to loopback by default; loopback is network posture, not an authentication substitute.
- Limit: a single local home is single-instance and guarded by a daemon lock.
Implementation Map
packages/local-runtime/src/daemon/boot.tspackages/local-runtime/src/daemon/postgres-supervisor.tspackages/local-runtime/src/runtime/compose.tsapps/desktop/src/daemon/packaged-entry.tspackages/api/src/app.ts