Centraid
Personal software. Your data. Your devices.
Centraid is a personal, local-first superapp: one shell wrapping many first-party apps over one vault — a shared personal ontology where your people, money, documents and plans live once. In v0 that vault lives on your phone, which is its sole authority and sole writer, and a machine you control — your laptop, a VPS, a NAS — runs a gateway that holds an encrypted backup it cannot read. Recovery is 24 words. There is no account, no subscription and no Centraid-operated service (#1029, scope amendment 2026-09-21, #1080).
Docs · Get started · Agents map · Contributing
Maintainer and support (F4)
Centraid is solo-maintained. Coding agents do much of the implementation; review and release confidence are the scarce resources.
| Expectation | Reality |
|---|
| Issue response | Best-effort; no SLA. Bugs with clear repro and security reports jump the queue. |
| Feature requests | Prefer a focused proposal; large unsolicited PRs may close. |
| Fastest support | Search docs, then file a bug. Report security issues privately, not as public issues. |
| Contributing | CONTRIBUTING.md — one focused change, linked issue, test evidence. |
What it does
- First-party apps — Docs, Photos, Notes, People, Locker, Calendar, Reminders, Money and Health, one crate each under
crates/apps. Calendar keeps events and Reminders keeps tasks; each has a tile, and tasks is the vault domain Reminders opens. They ship in the release and update with it; an app holds no database of its own and reads and writes the vault through typed commands.
- The phone is the vault — the Rust core on your phone holds
vault.db and is its only writer. It works fully offline because there is nothing to be offline from.
- Backed up to hardware you own — every gateway you pair holds a sealed copy of the vault and of every photograph, video and file in it, and can open none of it: no key, no plaintext, no schema. The phone reaches it over HTTPS straight to the machine, pinning the certificate the gateway's QR names; on an iPhone the system keeps uploading while Centraid is closed. Pair by scanning a QR the gateway prints.
- Recoverable from 24 words — every key derives from one BIP39 phrase. A fresh install plus the phrase brings the vault back. There is no kit file, no password and no escrow.
- Nothing hosted — no account, no subscription, no Centraid-operated service, no sharing plane. See the scope amendment of 2026-09-21.
How it works (30 seconds)
phone (SwiftUI/Compose)
core via core-ffi
┌───────────────────────── the vault, and its only writer ─────────────────────┐
│ vault: vault.db, the one writable connection, typed commands, │
│ custody, and the backup plane — snapshot, ranges, ledger, spool │
│ apps: photos · notes · docs · people · locker · calendar · reminders · money │
│ · health │
│ blobs: the content store identity: 24 words → every key │
└──────────────────────────────────────────────────────────────────────────────┘
│ uploads sealed parts: it DIALS, and accepts nothing
│ HTTPS straight to the gateway, its certificate pinned at pairing
▼
┌──────── centraid-gateway, on a machine you control (laptop, VPS, NAS) ───────┐
│ a blind store: sealed parts under names it cannot invert, the head under a │
│ compare-and-set, the writer epoch, purge and scrub │
└──────────────────────────────────────────────────────────────────────────────┘
- Apps are crates: a read plane of queries as pure folds over paged reads, and an action table whose writes are the vault's typed commands. An app crate holds no SQL and no connection; SQL is confined to the vault, ontology and search crates and the app kit by a gate rule.
- The gateway is a protocol, not a program:
crates/gateway's rules hold every decision with no I/O, with a conformance suite that runs in memory and over the wire, and the server is one adapter over them.
- The phone opens nothing:
no-listening-socket is a structural gate rule, and it refuses a listener or an accept anywhere but the gateway's one serve file.
Get started
Prereqs: a Rust toolchain (the version is pinned in rust-toolchain.toml); Bun for the repository tooling (release scripts, the docs and home sites, the product lints); a JDK and the Android SDK or Xcode for the mobile shells (mobile/README.md).
# the gateway: mints its identity, listens on 8443, and prints a pairing QR
cargo run -p centraid-gateway --bin centraid-gateway -- serve --data-dir ./gw-data
# another QR, beside a running serve
cargo run -p centraid-gateway --bin centraid-gateway -- pair --data-dir ./gw-data
Scan the QR from a phone build, then compare the safety number the phone shows with the safety line serve prints once it pairs. A QR admits one phone's vault, once, within a day, so a second phone needs a second pair.
Layout
| Path | What it is |
|---|
crates/ | The Rust core: the identity model, the vault and its backup plane, the ontology, the gateway protocol and its one deployment, the byte plane, one crate per app, the five-symbol C ABI, the protobuf schema workspace and the xtask gate. |
contracts/ | The layer every language reads: the DDL of a new vault and the list of its commands, the migration ladder, the screen fixtures, the crypto vectors and the down-only ledgers. |
mobile/ | The C ABI binding, the Jetpack Compose shell, the SwiftUI shell, and the Maestro flows. The only shell. |
packages/test-kit | Shared TypeScript test helpers. |
design/ | The design source: tokens.toml (every value), icons.toml, the fonts and the mockups. cargo xtask design generates the shells' tables, the sites' sheet and the dark mockups from it, and the gate fails on drift. |
copy/ | Emitted artifacts: one copy leaf per app, written by one command and gated against drift. |
deploy/ | The container images, the OS service units and the installer. |
Gateway install
The gateway is the centraid-gateway binary, on any machine you control; deploy/README.md is the whole story.
- VPS / Linux:
deploy/vps/install.sh verifies the release's SHA256SUMS and the binary's identity stamp before installing, and never installs an OS service silently (--with-service prints the commands; --yes writes the unit; enabling is left to you).
- Service units:
centraid-gateway install writes a systemd user unit or a macOS LaunchAgent and never enables it (--dry-run writes nothing). No credential goes in any unit: the gateway is blind, and its data directory holds nothing that opens a vault.
- Docker: run on the host's network and mount durable storage at the data directory — a bare run loses the gateway's identity with the container, and every paired phone then refuses its replacement. The phone dials the addresses the pairing QR lists, which a container's own network would not make reachable.
Nothing goes in front of it. The phone opens HTTPS straight to the gateway and pins the certificate the gateway minted, so there is no reverse proxy, no TLS termination, no domain and no certificate authority; a port forward or a VPN is how a gateway away from home is reached.
Build / check
The tree is gated by one command, and it is the entrypoint CI runs:
cargo xtask gate --profile local # the edit-run loop, warm, under 2 minutes
cargo xtask gate --profile pr # what every pull request satisfies
cargo xtask gate --profile nightly # pr + the device lanes, which need attached phones
cargo xtask gate --profile release # nightly + the artifact-identity checks
cargo xtask gate --profile mobile-jvm # the Kotlin JVM suites and the generated-artifact drift check
cargo xtask rules # the structural rules alone
cargo xtask repo-root # which tree the path-based rules will scan
Give every worktree its own CARGO_TARGET_DIR — sharing one silently hands generated Rust between them (.claude/skills/rust/SKILL.md, Pitfalls).
The product's binaries:
# a gateway
cargo run -p centraid-gateway --bin centraid-gateway -- serve --data-dir ./gw-data
cargo run -p centraid-gateway --bin centraid-gateway -- pair --data-dir ./gw-data
cargo run -p centraid-gateway --bin centraid-gateway -- pairings --data-dir ./gw-data
cargo run -p centraid-gateway --bin centraid-gateway -- scrub --data-dir ./gw-data
cargo run -p centraid-gateway --bin centraid-gateway -- health --data-dir ./gw-data
cargo run -p centraid-gateway --bin centraid-gateway -- install --data-dir ./gw-data --dry-run
# the operator's binary
cargo run -p centraid -- doctor --data-dir ./gw-data --json # read-only, lock-free
The vault itself has no CLI: it lives on the phone, and every verb that used to reach it — seat, pair, backup, export, recover, native-host — went with the seat plane.
The full verb table, with what each one's state is in this build, is crates/centraid/README.md.
The shells:
cd mobile && ./gradlew mobileJvm # the shared module's JVM suites + the drift check
cd mobile && ANDROID_HOME=… ./gradlew -Pcentraid.android=true :androidApp:assembleDebug
bun install
iOS needs an Apple toolchain and is an owner hand-off — the exact commands are in mobile/README.md.
Formatting, linting and the TypeScript that remains (packages/test-kit and the tooling under scripts/) run through the root scripts: bun run format, bun run lint, bun run typecheck, and bun run check for all of them plus the tests. Enable the commit hooks once per clone with git config core.hooksPath .githooks.
Documentation
The docs (centraid.dev/docs) are Astro-built static HTML in scripts/docs-site — two personas, three pillars:
| |
|---|
| Start | Install → vault → first app → pair a gateway → always-on → the 24 words. §01–§05 pending a rewrite for v0 — they describe the desktop shell #1029 deleted |
| Data | The vault, consent & the outbox, sealed columns, connections & sync, automations, the assistant, blobs, search |
| Apps | The eight first-party apps, app anatomy, the install model, attach & link, the harness surface, mobile |
| Devices | The phone as the vault, gateways and their addressing, pairing by QR, pinned HTTPS, the writer epoch, the mobile app, and what v0 does not have |
| Ontology | The full logical model — schemas, entity map, ownership matrix, gateway contract, rules |
| Privacy | What Centraid holds and where. Pending a rewrite for v0 — its Google/Assist sections describe a path this release does not offer |
| Terms | Terms for Centraid. Pending a rewrite for v0, for the same reason |
AGENTS.md maps the durable docs agents and humans use to orient in this repo.
License
MIT.
