OpenVitals

Agent-native health operating system for proactive wellness software.

English | 简体中文

OpenVitals is an agent-native health data plane for personal wellness software. It ingests data from phones, wearables, and provider APIs; keeps provenance and freshness visible; derives deterministic wellness state; and exposes safe interfaces for apps, MCP tools, OpenClaw workspaces, SDKs, and local agents.

It is built for the failure modes that make health agents unsafe in practice: stale data, mirrored records, provider summaries mistaken for raw streams, and opaque scores that cannot be explained.

OpenVitals is wellness infrastructure, not a diagnostic system or medical device. It should not be used for clinical decision-making.

Open Source Core For ARVO

ARVO is the proactive health OS and product experience: it connects wearables, labs, and daily habits so a health companion can notice meaningful changes and nudge users toward action. Ari is ARVO's first health companion agent.

OpenVitals is the open source core underneath that product direction. It focuses on the reusable infrastructure that health agents need before they can be trusted with personal wellness context:

• ingesting Apple Health, Apple Watch, Oura, WHOOP, Health Connect, and future provider data;
• preserving provenance, freshness, source priority, and dedupe evidence;
• making provider delays, mirrored records, stale data, and missing signals explicit to agents;
• exposing the same semantics through REST, MCP, SDKs, OpenClaw workspaces, and mobile collector examples.

The ARVO product can build proactive coaching, reminders, and companion-agent workflows on top of this layer. OpenVitals stays focused on the data plane, runtime semantics, and developer surfaces.

Why It Exists

Most health integrations stop at "we connected the API." OpenVitals goes further:

• Honest data semantics: every record carries granularity, latency, source, confidence, freshness, and capture mode.
• Agent-safe outputs: MCP and REST responses say when data is delayed, mirrored, stale, missing, or incomplete.
• Local-first runtime: a single-node SQLite setup works for development, self-hosting, and hardware QA.
• Explainable scores: recovery, sleep, strain, circadian, and alert outputs can be traced back to evidence.
• Provider dedupe: direct Oura/WHOOP data can win over mirrored Apple Health copies without destroying the raw audit trail.
• Mobile collector path: iPhone HealthKit is the primary Apple Health connector; Apple Watch live heart rate is optional and only live during an active workout session.

Quickstart

Requirements:

• Node.js 22+
• pnpm 10+

pnpm install
pnpm demo

In another terminal:

export OPENVITALS_AGENT_TOKEN=ov_demo_user_ada_derived

curl -H "Authorization: Bearer $OPENVITALS_AGENT_TOKEN" \
  "http://127.0.0.1:3000/v1/scores?userId=user_ada"

Open the local tools:

• Dashboard: http://127.0.0.1:3000/dashboard
• API playground: http://127.0.0.1:3000/playground
• OpenAPI JSON: http://127.0.0.1:3000/v1/openapi.json

What You Can Build With It

• A local personal health agent that refuses to overclaim when data is stale.
• A family recovery dashboard with per-profile credentials and scoped tokens.
• An MCP server that gives another agent freshness-aware health context.
• A mobile companion app that uploads HealthKit / Health Connect samples.
• A provider adapter for a new wearable or fitness platform.
• An OpenClaw workspace that runs daily briefings and recovery check-ins.

Repository Map

Data Semantics

OpenVitals treats health data as evidence with context, not just numbers.

Provider boundaries are explicit:

• Apple Watch live heart rate requires the optional live workout collector path using HKWorkoutSession and HKLiveWorkoutBuilder.
• Historical Apple Health / Apple Watch data arrives through iPhone HealthKit as samples or episodes, not as a server-side live stream.
• Oura cloud APIs provide provider-mediated time series, daily summaries, and scores. They are not continuous raw sensor streams.
• WHOOP cloud APIs provide provider-mediated recovery, sleep, workout, strain, HRV, resting heart-rate, and zone summaries. They are not continuous raw HR streaming.

Provider Status

Run pnpm docs:generate to generate provider and MCP reference docs locally.

Runtime Modes

demo mode seeds deterministic data and demo tokens:

pnpm demo

live mode starts without seeded user state and is intended for real connector flows:

OPENVITALS_MODE=live pnpm --filter @openvitals/api demo

Bootstrap a live user:

curl -X POST "http://127.0.0.1:3000/v1/live/bootstrap" \
  -H "x-openvitals-admin: ${OPENVITALS_ADMIN_TOKEN:-openvitals-dev-admin}" \
  -H "content-type: application/json" \
  -d '{"userId":"user_live","name":"Live User","timezone":"UTC","createTokens":true}'

By default, runtime SQLite state is stored at .openvitals/openvitals.sqlite. Override it with OPENVITALS_DB_PATH.

Real Data Setup

Copy the example environment file and fill in only the providers you need:

cp .env.example .env.local

Useful guides:

• Documentation Index
• Real Data Quickstart
• Credentials Setup
• iOS Companion Guide
• iOS Hardware QA Runbook
• Hardware Test Plan
• Self-Hosting
• OpenRouter LLM
• OpenClaw E2E

Never commit .env, .env.*, OAuth codes, access tokens, refresh tokens, provider client secrets, Apple device identifiers, or real HealthKit exports.

OpenClaw And MCP

The upstream OpenClaw repository is pinned as a submodule at vendor/openclaw.

git submodule update --init --recursive
pnpm openclaw:e2e

The automated E2E starts the demo API, registers the OpenVitals MCP server in an isolated OpenClaw config, generates skill/workspace assets, and calls health.sync_status plus health.daily_brief over MCP stdio.

Generate an OpenClaw daily brief workspace:

pnpm --filter @openvitals/openclaw-skill exec openvitals-openclaw-init \
  --out-dir . \
  --api-base-url http://127.0.0.1:3000 \
  --user-id user_ada \
  --timezone UTC \
  --daily-cron "0 8 * * *" \
  --weekly-cron "0 9 * * 0" \
  --webhook-secret local-dev-secret

Development

pnpm docs:generate
pnpm build
pnpm test
pnpm smoke:e2e
pnpm typecheck
pnpm smoke:apple-health
pnpm provider:new fitbit

CI runs docs generation, build, unit tests, smoke E2E, and typecheck.

Contributor guardrails:

• Keep score computation deterministic and explainable.
• Preserve raw/provider payload history and normalized records.
• Do not hide stale, mirrored, missing, or incomplete data from agent-facing outputs.
• Do not weaken token scope behavior, OAuth handling, webhook signing, or admin boundaries.
• Do not make diagnostic, treatment, or medical-device claims.

See CONTRIBUTING.md for more.

License

OpenVitals is source-available for noncommercial use under the PolyForm Noncommercial License 1.0.0. Commercial use requires a separate commercial license. See COMMERCIAL.md.

This is intentionally not an OSI-approved open-source license because the project does not grant unrestricted commercial use.

Disclaimer

OpenVitals is for wellness, coaching, self-tracking, and agent context workflows. It is not a diagnostic system, not a medical device, and not a substitute for clinical judgment. Always show provenance, confidence, and freshness before making health-related claims.