Concept: self-contained desktop build — bundle the omadia backend so the app runs standalone (no Docker)

[iret77]

Concept — not yet scheduled. Captures a research session's findings so this can be picked up.

Goal

Make the omadia-ui desktop app self-contained: bundle the omadia backend so a non-technical user can double-click an installer and get a working local omadia — no Docker, no separate server to run. This is the "native installer" path (Path a) of the onboarding effort tracked in byte5ai/omadia#337.

Today omadia-ui is a canvas client that connects to a separately-running omadia server (app/src/main/discovery.ts / auth.ts; default ws://127.0.0.1:8181/omadia-ui/canvas). This issue is about shipping a build variant that brings its own backend.

What already exists (reusable foundation)

• Electron shell, electron-vite, electron-builder, auto-release pipeline for macOS (dmg arm64/x64), Windows (NSIS), Linux (AppImage).
• Signing capability — not a blocker (byte5 has an Apple Developer account; current ad-hoc signing is a deferred config choice, not an inability).
• Lume renderer, server discovery + login.

What needs building

Building block	Status	Note
middleware sidecar	new	lifecycle manager in app/src/main (spawn/kill); PLATFORM_DATA_DIR → OS app-data dir
embedded Postgres + pgvector	new	e.g. @boomship/postgres-vector-embedded; per-OS/arch binary
web-ui as a bundled, interim admin surface	new	see "two-UI reality" below
seed first admin on first boot	new	the client cannot create an admin — call kernel /api/v1/auth/setup on first run
local-default discovery	small	point VITE_OMADIA_WS_URL at the co-bundled backend

The two-UI reality (verified against both repos)

The canvas client and the operator UI are distinct front-ends, not redundant:

Flow needed for a real trial	canvas (omadia-ui)	web-ui (Next.js, in byte5ai/omadia)
first-admin setup + LLM key / provider	✗	✓ /setup, /admin/providers
Agent Builder (elementary — omadia isn't really usable without it)	✗	✓ /admin/builder
run an agent + chat	✓	✓
audit-receipt / run trace	✗	✓ /routines/.../runs

The canvas channel exposes only discovery + the WS canvas protocol; Setup/Builder/Audit are web-ui/kernel routes. So the self-contained app must bundle web-ui as an interim admin layer alongside the canvas, until the canvas covers Setup/Builder/Audit itself (planned, but not soon — capacity-bound). Bundle = canvas (host UI) + web-ui (interim admin) + middleware + embedded Postgres.

Engine / key

API key via the Setup wizard today. byte5ai/omadia#309 (subscription via the official CLI) makes it key-free later — caveat: in a double-click app the Claude CLI would have to be bundled/required, whereas the setup-prompt path (Path b) gets it for free since the installing agent already runs on the subscription.

Cross-platform note

The hard part is not the shell or signing (both already exist for 3 OSes) — it's the native backend deps (argon2, better-sqlite3) + the Postgres binary per OS/arch. Open scope question: mac-first (use the existing Apple setup, Mac-leaning evaluator base) vs. all 3 OSes at once.

Related

• byte5ai/omadia#337 — onboarding hub (Path a/b/c)
• byte5ai/omadia#293 — UI↔host pairing (related but distinct: that's remote/LAN pairing; this is client+host in one bundle)
• byte5ai/omadia#309 — subscription engine (key-free path)

Status

Concept. A hands-on dry-run of the non-Docker install (to measure real robustness + produce the build steps) is the next step.

[iret77]

Update — converged with @Weegy's omadia.app architecture sketch

@Weegy — your omadia.app sketch matches this issue's concept almost 1:1: an Electron supervisor in the main process that forks the middleware (dist/index.js, unchanged) + the web-ui Next server as child processes, an embedded DB exposed over the Postgres wire protocol on 127.0.0.1, and a window pointing at the web-ui (= the real admin UI). Folding the convergence + one decision in here so we share one thread instead of two.

DB choice — PGlite (your pick) is the right default for this app

This issue originally proposed an embedded Postgres binary (@boomship/postgres-vector-embedded). For this app, PGlite is the better call — because the trade-offs that favored a real binary are production / scale concerns, and we've explicitly scoped this to a local trial, not a production system (production = a clean server/VPS install, decided upthread):

• Single-connection / serialized → one test operator, minimal concurrency → non-issue here.
• pgvector maturity/perf in PGlite (via @electric-sql/pglite-pgvector) → small trial data → non-issue here.
• Upside stays: pure WASM/npm, no per-OS/arch Postgres binary to build, sign, and ship — the native-deps burden in the table above largely disappears. That's a real maintenance win.

So: PGlite = default; the embedded binary drops to a fallback, only if the check below fails — not a co-equal option.

The one real check left — "does it run at all", not scale

Do omadia's middleware migrations + the pgvector KG queries run cleanly against PGlite? PGlite is PG-compatible but not 100% (WASM Postgres ~16 vs. the usual pgvector/pgvector:pg17), and pgvector there is an external extension that must be loaded. This is binary (works / doesn't), independent of trial-vs-prod, and it falls out of the planned hands-on non-Docker install dry-run anyway.

Where this sits

• This is Path a of the onboarding effort (Lower the barrier to try omadia (no-Docker eval path) omadia#337).
• The prebuilt-image / minimal-core stack you shipped in feat: minimal-core onboarding stack (prebuilt images + opt-in overlays) omadia#339 is the complementary Docker path (Path c).
• The setup-prompt / public-skill-file path is Concept: setup-prompt onboarding — agent-driven local install via a public skill file omadia#338 (Path b).
• One verified constraint to carry over: the canvas client can't do Setup/Builder/Audit yet, so the app must bundle web-ui as the (interim) admin surface — which your sketch already does (window → web-ui).

[iret77]

Closing — implemented. The self-contained desktop app concept proposed here shipped in byte5ai/omadia#341 (merged): a native one-click installer under omadia's desktop/ — an Electron supervisor forking the existing kernel + web-ui (unchanged) over an embedded PGlite, exactly the architecture sketched in this issue.

It also resolved the PGlite checks raised above:

• single-connection → GRAPH_POOL_MAX=1
• migration parity → pgcrypto dropped (gen_random_uuid is core PG13+)
• pgvector + pg_trgm loaded

Build/sign CI follows in byte5ai/omadia#342.

Note: the app landed in byte5ai/omadia (desktop/), not here — it bundles middleware + web-ui, which both live there. My earlier "not yet in code" comment is superseded as of #341. Onboarding overview: byte5ai/omadia#337.