How it works

One protocol.
Three tiers.

Storage holds the events. OHDC moves them. Consumers — humans or agents — read and write under grants the user issues, scopes, and revokes. This page is the technical view of the project.

Read the spec spec/README.md Run your own docker compose

The OHDC protocol

One Connect-RPC API, three auth profiles.

Every consumer — your Connect app, a clinician's Care SPA, an AI agent over MCP, a paramedic's tablet — speaks the same wire to your storage. Different identities, different scopes, same protocol.

Self-session

You, talking to your own storage. Bootstrapped from a BIP39 mnemonic; a self-issued bearer (ohds_…) authenticates subsequent requests.

Grant token

A scoped, time-bound credential another party uses on your behalf. Per-channel, per-class, optionally per-tool. Revoking it makes the consumer's next call fail.

Device token

Long-lived credentials for trusted devices you own — your phone, your home server, a paired tablet. Issued and revoked from the storage admin surface.

Connect-RPC over HTTP/2 for browsers and mobile clients, plus HTTP/3 (quinn + h3) opt-in for low-latency native paths.
Per-channel XChaCha20-Poly1305 for sensitive classes — mental health, sexual health, substance use — with separate keys derived from a class hierarchy.
X25519 ECDH multi-storage grants: a grant can be re-targeted between your storages without re-issuing.
Source signing (Ed25519 / RS256 / ES256) over canonical CBOR — events carry tamper-evident provenance.
Two-sided audit: operators see who their staff queried; patients see who queried them.
Synchronous revocation. Pull a grant; the consumer's next call is denied.

Architecture

Three tiers. One protocol.

Consumers

Connect

Web, Android, CLI, MCP. Personal logging and dashboards.

Care

Clinician roster, cases, write-with-approval, two-sided audit.

Emergency

Paramedic-scoped beacon read with authority signing.

Your AI agent

Any MCP-aware client. Acts under explicit user grants.

OHDC over Connect-RPC + HTTP/3 grants · channels · audit log · revocation

Storage

On your phone

Embedded SQLite (SQLCipher) via uniffi.

Home server

Docker compose, single VPS, or NAS.

OHD Cloud

Managed instance, same protocol.

Clinic operator

Self-hosted, OIDC-delegated.

Relay — NAT-bridges home instances over a raw QUIC tunnel (ALPN ohd-tnl1) and signs emergency-authority tokens.

What's built

Real, not just spec.

Reference implementations across mobile, web, CLI, and MCP — with an end-to-end test suite. The goal is to show every interesting flow already running.

11 form factors

3 web SPAs (Connect / Care / Emergency dispatch), 2 Android Compose apps, 4 CLIs, 3 Python+FastMCP servers — all against the same OHDC protocol.

600+ tests

Across the project: protocol-level integration tests, encryption invariants, grant lifecycle, audit semantics, cross-language FFI bindings.

Native packages

.deb for Debian / Ubuntu, .rpm for Fedora / RHEL, Arch PKGBUILD. Systemd units, sane defaults, log rotation.

Docker compose stacks

Per-component compose files plus a top-level docker-compose.yml that brings up the whole reference stack on a single host.

Run your own

The full stack on your machine in one command.

Local stack

git clone https://github.com/ohd-foundation/ohd
cd ohd
docker compose up --build -d

Brings up storage, relay, Connect, Care, Emergency, and the three MCP servers. Open http://localhost:8080 for the Connect web app.

Single-host deployment

The live ohd.dev reference deployment runs on a single Hetzner ARM box — Caddy, storage, relay, all in compose. Recipe in DEPLOYMENT.md.

DEPLOYMENT.md →

Bring your own identity

Plug in any OIDC provider — Google, Okta, Authentik, Keycloak — or use the storage's built-in OAuth endpoints for small deployments.

AI agents

Three MCP servers. Yours to wire to any LLM.

Each server exposes OHDC operations as MCP tools. Drop them into Claude Desktop, Claude Code, or any MCP-aware client. Grants are checked per call; audit entries are written on every read.

Connect MCP

Personal context. Read your events, write new ones, manage your own grants. For the assistant on your side of the conversation.

connect/mcp →

Care MCP

Clinical context. Roster, cases, write-with-approval, two-sided audit. For an assistant working alongside a clinician.

care/mcp →

Emergency MCP

Authority-signed beacon reads, scoped to an active case, with full audit. For dispatch-side and on-scene assistants.

emergency/mcp →

Specification

Build any client.

Wire protocol, event vocabulary, grant model, encryption, and audit semantics — all in /spec. Reference implementations under /connect, /care, /emergency.

Spec entry point

Start at spec/README.md. Then spec/docs/00-vision.md for the why, and spec/docs/design/ for the how.

Open the spec →

Repository

Dual-licensed Apache-2.0 OR MIT. Issues, discussions, and PRs welcome.

github.com/ohd-foundation/ohd →

One protocol.Three tiers.