Run Omi fully on-prem: storage behind a neutral, swappable port (Firestore | Mongo)

[abunet]

"The next AI moat isn't intelligence. It's personal context."
"By collecting ALL data about the user… we commit to privacy and open-source."
"We use open source as a trust wedge." — the manifesto

First, thank you for building Omi in the open — betting on personal context as the moat, and on open source as the trust wedge, is exactly right, and it's what made us want to contribute rather than just watch.

This PR delivers the first milestone from #10884 : the datastore. We took the manifesto at its word. If Omi's edge is all of a person's context, and open source is the trust wedge, then the strongest possible proof of the privacy commitment — the one an enterprise security team will actually accept — is simple: you can run the whole thing yourself, and no byte of context has to leave your walls.

So we made the backend run entirely on-prem, with storage sitting behind a neutral abstraction that has real, interchangeable implementations. The cloud backends stay first-class for everyone who wants them. Nothing about the hosted product changes; we just made "host it yourself, keep your data" a supported, tested reality.

• The backend boots and serves with zero cloud egress (hermetic compose).
• Every persistence call now goes through a neutral document-store port; Firestore (reference) and MongoDB (proof the abstraction is real) are drop-in, config-selected implementations (STORAGE_BACKEND).
• Parity between backends is enforced by a dual-backend contract test running against a real Firestore emulator and a real Mongo replica set.
• A CI guard keeps the boundary from eroding: only database/ may touch a raw persistence client.

What landed

Offline baseline (WP0) — a hermetic deploy/onprem/ compose (backend + Firestore emulator + Valkey) on an internal: true network; proven no-egress. Runbook in deploy/onprem/SELFHOST_NOTES.md.

Sealed the persistence boundary (WP1) — database/ is now the only door to the datastore, enforced by an AST guard (.github/scripts/check_firestore_persistence_boundary.py, exit 0 = clean). No more db.collection(...) scattered across routers/utils.

Neutral storage port + two implementations (WP2) — a small, backend-agnostic DocumentStore port (backend/database/store/) that speaks logical paths + plain dicts + neutral sentinels, never Firestore snapshots. Surface: get / set / update / delete / exists / query / query_group / count / get_many / list_ids / delete_recursive / run_transaction / batch, with keyset pagination and array_contains / multi-field ordering. Two adapters behind it — a Firestore reference adapter and a MongoDB adapter (single-node replica set for transactions) — plus an in-memory fake for tests.

Migrated the entire data layer — all ~50 backend/database/*.py modules now run on the port (users, conversations, chat, apps, the whole memory subsystem, task-intelligence, desktop, sync, and the long tail), including their transactions and collection-group queries. The injected raw-client threading was removed end-to-end; no compatibility shims were left behind (per the repo's no-compat rule — every in-tree caller migrated in the same change).

Kept everyone honest with tests — a dual-backend contract suite proves the two adapters behave identically against real services; a reproducible offline test image and a parallelized, file-isolated test sweep gate every change against a branch-point baseline (net regressions: zero).

Wrote the decisions down — the initiative is captured as a set of ADRs (on-prem goal, uniform abstraction pattern, the port's shape and its incremental extensions, the deliberate deviations from upstream conventions, and the offline test harness), so the why travels with the code.

Principles we stuck to

• Cloud stays first-class. Firestore/GCP remain the default and are fully supported; on-prem is an option, not a replacement. (A second implementation existed mostly to prove the abstraction wasn't secretly Firestore-shaped.)
• One honest exception. Push notifications are the single genuinely cloud-bound feature; they sit behind a feature flag rather than pretending to be on-prem.
• No in-repo compatibility layers. Migrations updated every caller in the same change — no deprecated aliases, no dual code paths.

Not in scope (on purpose)

Historical data migration between backends, a pure-on-prem push transport, and adopting a graph/vector engine as the implementation are explicitly deferred (see ADRs). This PR is about making the datastore swappable and the backend self-hostable — not about moving anyone's existing data.

What's next — the rest of the road to zero cloud

Storage is the biggest cloud dependency, but not the only one. The same "neutral port + interchangeable implementations, cloud stays first-class" pattern applies to the remaining touchpoints, and each is a natural follow-up (tracked in #):

• Auth (OIDC). Abstract identity behind a provider port so it's Firebase Auth or a self-hosted OIDC provider (e.g. Keycloak). An enterprise brings its own IdP; tokens are verified locally, no Google dependency in the request path.
• Vector store. Put semantic memory behind a vector port so it's Pinecone or a self-hostable engine (e.g. Qdrant) — embeddings and recall stay on your infrastructure, which for "all of a person's context" is exactly the data you least want to ship out.
• Object storage (S3). Route audio/artifacts through an object-storage port so it's GCS or any S3-compatible on-prem store (e.g. SeaweedFS / RustFS). Raw recordings never have to touch a public bucket.

Land those three and the loop is closed: identity, structured data, vectors, and blobs all run on-prem, with the hosted cloud stack still the default for anyone who prefers it. Each ships the same way this one did — abstraction first, a real second implementation to prove it, contract tests for parity, no compatibility shims.

How to try it

cd deploy/onprem
cp backend.env.example backend.env && sed -i "s/^ENCRYPTION_SECRET=.*/ENCRYPTION_SECRET=$(openssl rand -hex 32)/" backend.env
docker compose up -d --build          # 3 services become healthy, no internet needed at runtime
docker compose exec -T backend curl -fsS http://localhost:8080/v1/health   # {"status":"ok"}

Flip STORAGE_BACKEND to point the same code at Firestore or Mongo. Offline test recipe and the dual-backend contract run are documented in SELFHOST_NOTES.md.

---

Open source as a trust wedge only cuts if people can actually pick it up and run it. Now they can — on their own metal, with their own data, for real. 🔓