Zephr Docs

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" .-> API

The 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

ComponentRole
zephr-mcpThe MCP server over stdio; the agent's tool surface
zephr CLIBootstrap, evidence, continuity, sync, diagnostics verbs
zephrd daemonOne Rust binary with daemon, stdio, cli, hook, lsp modes
SQLite storeBeliefs, FTS5 lexical index, sqlite-vec vectors, receipt chain
Hook transportzephrd --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.

MethodPathOperation IDStatus
POST/auth/loginauthLoginshipped
POST/auth/signupauthSignupshipped
POST/auth/logoutauthLogoutshipped
GET/auth/sessionauthSessionshipped
GET/pulse/systemgetSystemHealthshipped
GET/runtime/statusgetRuntimeStatusshipped
GET/memorylistMemoriesshipped
POST/memorycreateMemoryshipped
GET/memory/{id}getMemoryDetailshipped
PUT/memory/{id}updateMemoryshipped
DELETE/memory/{id}deleteMemoryshipped
POST/memory/recallrecallshipped
POST/memory/rememberremembershipped
GET/source/projectslistProjectsshipped
POST/codebase/searchsearchCodebaseevolving

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) recognizes sqlite, postgres, and qdrant-hybrid and ships only the SQLite adapter live. The postgres profile's getBackend() fails closed with PostgresBackendNotImplemented when 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 (createPostgresBackend in packages/store-postgres/src/pg-backend.ts): a real pg-backed implementation of the graph, recall, review, vector, admission, and purge ports, with an unforgeable tenant-scope registry and every tenant operation running under SET LOCAL ROLE tenant_request plus app.installation_id and 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:

  1. 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).
  2. Captured memories — when you use cloud-backed storage, beliefs and provenance are stored on the cloud plane.
  3. Source ingestion — when cloud code intelligence is enabled. A zephr status egress 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-audit is 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.sql LIST-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); the 0182 migration 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_failure with 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/live getBackend() contract and PostgresBackendNotImplemented.
  • 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.