Daemon Initialization & Architecture

Umbra runs a persistent background process (the daemon) that owns the task queue, holds the SQLite connection, and exposes an HTTP gateway on 127.0.0.1:8080 (configurable in config.json). The CLI is a thin client that talks to this gateway.

Startup flow

umbra start
  └─ ensureDaemonWithPm2()          # registers & starts the PM2 process
       └─ src/core/daemon-entry.ts  # daemon entry point
            └─ startDaemonRuntime()
                 └─ startDaemon()
                      ├─ loadConfig()          # reads config.json
                      ├─ getMemoryManager()    # opens SQLite, loads sqlite-vec
                      └─ HttpGateway.start()   # binds the HTTP port

PM2 process management

The daemon is registered with PM2 under the name umbra-daemon. PM2 restarts it automatically if it crashes and persists it across reboots.

umbra daemon start    # start the daemon in the background
umbra daemon stop     # stop the daemon
umbra daemon status   # show health and queue depth
umbra daemon status --json  # machine-readable output

# short aliases also work
umbra start
umbra stop
umbra status

umbra daemon status returns fetch failed when the daemon is not running — this is expected, not a bug.

You can also use PM2 commands directly:

pnpm daemon:start    # start via ecosystem.config.cjs
pnpm daemon:stop
pnpm daemon:delete   # remove from PM2 entirely

Runtime layout

All runtime state lives in ~/.umbra/ by default. Set the UMBRA_HOME environment variable to redirect everything to a different path (useful for testing or multi-instance setups).

~/.umbra/
├── main.sqlite          # single database for all projects
├── settings.json        # runtime settings
├── providers.json       # provider profiles & API keys
├── sessions/            # session transcripts
├── projects/            # per-project metadata
├── cache/
│   └── transformers/    # cached embedding model weights
├── drafts/
├── exports/
└── debug/
    ├── events.jsonl     # structured debug events
    └── latest.log

Native ABI note

better-sqlite3 is a native addon. It must be compiled for the exact Node.js ABI used by the PM2 process. If the daemon crashes on startup with a NODE_MODULE_VERSION error, run:

pnpm rebuild:natives:match-daemon
pnpm daemon:delete
umbra start