Local and cloud
Zephr is local-first, and it is not local-only. This page draws the boundary exactly. For what is (and is not) encrypted at rest in local mode, read Security and privacy.
flowchart TB
subgraph local[Your machine — local plane]
MCP[zephr-mcp over stdio]
CLI[zephr CLI]
D[zephrd daemon]
DB[(SQLite store)]
E[On-device embeddings]
MCP --> DB
CLI --> D
D --> DB
E --> DB
end
subgraph cloud[Cloud plane]
API[/api/cloud mount/]
AUTH[OAuth + JWT verification]
PG[(Managed Postgres + RLS)]
KMS[KMS envelope encryption]
W[Workers]
API --> AUTH --> PG
API --> W
PG --- KMS
end
CLI -. "sync + cloud commands (explicit)" .-> API
MCP -. "nothing in local mode" .-> APIThe posture: local is an edge, never a second authority
The baseline states it as a rule: local mode is a capture edge and a compile target, never a second source of truth (the platform spec records this posture as stated). On the cloud plane the local store holds no authority: it cannot resurrect a fact erased on the cloud plane, and reconciliation runs through sync, not parallel writes.
In local mode the boundary is simple: the MCP server speaks stdio JSON-RPC to
the client that launched it. With the default configuration — on-device
embedding — lexical search, semantic vectors, and embeddings all run on your
machine, and if the semantic tier is unavailable, recall degrades to
lexical-only and says so rather than waiting on the network. Embeddings can
also be pointed at a remote provider: a LiteLLM or OpenAI-compatible endpoint
configured through LITELLM_BASE_URL / LITELLM_API_KEY /
OPENAI_API_KEY (packages/core/src/embedding/litellm.ts). That traffic is
your configuration and goes where you point it — it is not part of the
default local posture.
What runs locally
| Component | Role |
|---|---|
zephr-mcp | The MCP server over stdio; the agent's tool surface |
zephr CLI | Bootstrap, evidence, continuity, sync, diagnostics verbs |
zephrd daemon | One Rust binary with daemon, stdio, cli, hook, lsp modes |
| SQLite store | Beliefs, FTS5 lexical index, sqlite-vec vectors, receipt chain |
| Hook transport | zephrd --mode hook: one event in, spool append, exit |
The daemon is not a service you manage: any CLI/MCP invocation auto-spawns it when its socket is absent, it shuts down when idle, and killing it cannot corrupt the store (opened read-only during recovery; spool records survive and drain on the next start).
What runs in the cloud plane
The cloud application layer is reached through /api/cloud, the single
canonical mount — it lives inside the web application today, not as a separate
deployable. Behind it: OAuth 2.1 routes and JWT verification, managed Postgres
as the only authority (forced row-level security on the core tenant tables), KMS
envelope encryption, the Rust data plane that never terminates customer trust,
and workers. The Rust query path never serves tenant payload from the vector
index — every hit is joined back and re-authorized against Postgres before
disclosure.
The publicly documented cloud routes
The inventory below is the reviewed public-disclosure subset generated from
apps/docs/generated/openapi-operations.json; it is not the complete cloud contract.
See generated OpenAPI operations.
Fourteen disclosed operations are shipped; searchCodebase (POST /codebase/search)
is evolving.
| Method | Path | Operation ID | Status |
|---|---|---|---|
| POST | /auth/login | authLogin | shipped |
| POST | /auth/signup | authSignup | shipped |
| POST | /auth/logout | authLogout | shipped |
| GET | /auth/session | authSession | shipped |
| GET | /pulse/system | getSystemHealth | shipped |
| GET | /runtime/status | getRuntimeStatus | shipped |
| GET | /memory | listMemories | shipped |
| POST | /memory | createMemory | shipped |
| GET | /memory/{id} | getMemoryDetail | shipped |
| PUT | /memory/{id} | updateMemory | shipped |
| DELETE | /memory/{id} | deleteMemory | shipped |
| POST | /memory/recall | recall | shipped |
| POST | /memory/remember | remember | shipped |
| GET | /source/projects | listProjects | shipped |
| POST | /codebase/search | searchCodebase | evolving |
Where the local and cloud bridges do not connect
Labeled precisely, so nothing here is assumed:
- The local admission chain does not run on the cloud path. The trusted launcher, launch capability, and binding epoch (Identity and admission) exist over the local SQLite store. Cloud requests authenticate through Supabase sessions, OAuth tokens, or API keys instead — the stateless per-request cloud scope validation mirroring the local chain is designed, not shipped.
- The backend profile registry wires SQLite live; Postgres is live when
configured. The core registry (
packages/core/src/backend/profile.ts) recognizessqlite,postgres, andqdrant-hybridand ships only the SQLite adapter live. Thepostgresprofile'sgetBackend()fails closed withPostgresBackendNotImplementedwhen constructed without a connection string and allowed worktree ids — the fail-closed stub behavior the conformance suite pins. With a connection string it returns the live adapter (createPostgresBackendinpackages/store-postgres/src/pg-backend.ts): a realpg-backed implementation of the graph, recall, review, vector, admission, and purge ports, with an unforgeable tenant-scope registry and every tenant operation running underSET LOCAL ROLE tenant_requestplusapp.installation_idand forced row-level security. Unconfigured never degrades to a default — but the backend is not "not implemented"; the error is the missing-configuration path.
What crosses the boundary
Three things cross, and each is named:
- Sync state and the workspace snapshot — MCP server configs, rules, commands, hooks, model preferences, env references, and tool policies. The cloud table is authoritative for cross-device coherence; the local cache answers offline queries and reconciles on reconnect (cloud wins, with a notice).
- Captured memories — when you use cloud-backed storage, beliefs and provenance are stored on the cloud plane.
- Source ingestion — when cloud code intelligence is enabled. A
zephr statusegress row stating the bytes transmitted and the evidence-pointer count is designed (surfaces-spec requirement; not implemented in the status command today).zephr pod egress-auditis also a designed/stubbed surface: its default client and development store return no measured records.
Nothing crosses implicitly. With the default local configuration, no network call is made as part of normal operation; a configured remote embedding provider (above) is the exception, and it goes where you point it.
Isolation tiers
The tier ladder is the designed boundary — the platform spec's amendment ("the isolation boundary between tiers follows the six-tier ladder, not volume") — and the build states below are the platform spec's own records:
- Shared tiers (Pro/Premium/Max) — partitioning machinery exists:
checksummed migration
0182_cell_list_partitioning.sqlLIST-partitions the ANN/BM25-backing tables (belief_version,lens_lexical_document,vector_projection) by installation id. The platform spec records the requirement PARTIALLY SATISFIED (reviewed build state); the0182migration corroborates the LIST-partition obligation, and the amendment's partitioned pgvector/pg_textsearch memory plane is the target. - Team / Enterprise — dedicated-database provisioning is
uncorroborated: the isolation machinery exists (the partitioning
migration and
packages/store-postgres/src/cell-router.ts), but no provisioning-before-entitlement path is located in source or tests. - Cell registry and connection router — NOT SATISFIED per the reviewed baseline: no cell registry authority for every installation's data plane (spec build state).
- Residency — PARTIAL: the pinning-constraint columns ship
(
lens_repo.residency,lens_embedding_collection.residency), and end-to-end ingest-gate enforcement is not wired. - BYOK — designed: no shipped source for storage-level BYOK was located in this pass.
Failure behavior at the boundary
- Offline — local features keep working; sync queues locally and reconciles on reconnect, failing closed rather than overwriting the cloud-authoritative state silently.
- KMS unavailable — the designed rule is "degrades to unreadable, never to
plaintext": decryption failures surface as a structured
kms_failurewith no plaintext fallback. Implemented in code, not yet proven end-to-end by a test — a designed guarantee, not a rehearsed one. - Degradation is named. Whenever a plane degrades, the response says which tier or plane is degraded. See Troubleshooting.
Sources
openspec/specs/platform/spec.md— local-mode posture, authority rules, isolation and residency requirements.openspec/specs/surfaces/spec.md— offline function and the egress row.apps/docs/generated/openapi-operations.json+packages/protocol/openapi/cloud-v1.yaml— the canonical public route inventory (primary).packages/store-postgres/src/profile.ts— the stub/livegetBackend()contract andPostgresBackendNotImplemented.packages/store-postgres/src/pg-backend.ts— the live adapter, tenant-scope registry, and RLS gating.packages/core/src/backend/profile.ts— the recognized backend kinds and the live SQLite adapter.crates/zephr-cloudd/src/query_joinback.rs— the vector join-back invariant.