PulsHealth
GitHub

Documentation

Start with server setup, then explore your data through the dashboard, API or an AI assistant. Each guide links to the details you need along the way.

Set up with a coding assistant

Help me set up PulsHealth on my server. Read https://pulshealth.com/llms.txt and https://pulshealth.com/docs/setup/ first. Check my machine, network and existing installation, then follow the guide. Preserve existing data and keep secrets out of chat. Help me pair my iPhone and verify that synced data arrived.

Use an assistant with terminal access to your server, or follow the setup guide yourself.

Bring your own server.

For AI tools: documentation index · setup guide as Markdown

Explore cool examples
What could you build with your health data freed from your phone?

Getting started

Set up a server, connect an assistant to synced data, or use the app on its own.

Set up your server
Follow the setup steps yourself or give them to an AI assistant: install, connect your iPhone, verify the first sync and keep a backup.

Read the guide

Connect AI to your data
After your phone is syncing, give a compatible assistant read-only access through MCP, or share a summary.

Read the guide

Explore and export on your iPhone
Use the app without a server. Explore Apple Health, export files, or choose the types to sync.

How it works

Use a hosted account
We run the database, the web viewer and the AI connection for you. Create an account and connect the app to it.

Get started

Reference

Configuration, data formats and interfaces when you need the details.

Understand how health data is recorded
Recording frequency, coverage, sources, context and the difference between raw records and daily summaries.

Read the guide

Server configuration and operations
The Docker Compose stack: bootstrap, configuration, exposing ingest, schema migrations, backups and restore, and upgrading the published images.

Read the guide

Puls Sync Protocol v1
The wire format the app speaks, written for anyone implementing a receiver: line types, JSON Schemas, canonical units, idempotency and the retry contract.

Read the guide

Database guide
What the database stores, how the schema is shaped, and how to query it without misreading the health data, including iPhone plus Watch double counting.

Read the guide

Product API
The read-only HTTP API over your health data: a quickstart, authentication, choosing the user, conventions, paging, errors and rate limits.

Read the guide

API reference
Every product API endpoint with its parameters, responses, fields and a curl example, rendered from the OpenAPI 3.1 document the service serves.

Read the guide

Bulk export
Export CSV, JSON or JSONL from the app without a database, with custom summaries and CSV layouts; or stream CSV or JSONL from the product API and CLI.

Read the guide

MCP server
The Go MCP server that gives AI assistants read-only tools over the product API: the tools, the stdio and HTTP transports, and how to run it.

Read the guide

Web viewer
The self-hosted Next.js viewer that reads your Postgres directly: quick start, connecting to real data, the optional login and the container image.

Read the guide

PulsHealthSync Swift package
The dependency-free Swift package underneath the app: the sync engine, transport and NDJSON encoding, embeddable in another iOS app.

Read the guide

Self-hosting overview
What runs on your server, how your phone connects, and what you maintain.

See what is included

Project

How the project is run: reporting problems, what shipped, what is next.

Security policy
Supported versions, how to report a vulnerability privately, the threat model, and the trust boundaries of each token.

Read the guide

Changelog
What changed in each release of the server stack, the four images that share one version selected by PULS_VERSION.

Read the guide

Roadmap
What is still outstanding, in the order worth doing it, tied to the requirement IDs of the open-source plan.

Read the guide

What the app syncs

81 Apple Health types, grouped the way Apple Health groups them. Nothing is read until you turn a type on and iOS grants permission. Workouts carry their GPS routes and per-second sensor series; ECGs bring their microvolt trace; State of Mind, sleep apnea events and medication doses come across on the iOS versions that support them.

Activity27
Heart14
Body8
Respiratory2
Sleep3
Nutrition9
Vitals5
Workouts1
Other12
Every type, by nameshow 81

Activity

  • Active Energykcal
  • Activity Rings
  • Cycling Cadencecount/min
  • Cycling Distancem
  • Cycling PowerW
  • Cycling Speedm/s
  • Double Support %%
  • Exercise Minutesmin
  • Flights Climbedcount
  • Ground Contact Timems
  • Move Minutesmin
  • Physical Effortkcal/hr*kg
  • Resting Energykcal
  • Running PowerW
  • Running Speedm/s
  • Running Stride Lengthm
  • Stand Hours
  • Stand Minutesmin
  • Step Lengthm
  • Stepscount
  • Swimming Distancem
  • Swimming Strokescount
  • Vertical Oscillationcm
  • VO₂ Maxml/kg*min
  • Walking + Running Distancem
  • Walking Asymmetry %%
  • Walking Speedm/s

Heart

  • AFib Burden%
  • ECG
  • Heart Ratecount/min
  • Heartbeat Series (beat-to-beat)
  • High HR Events
  • HR Recovery (1 min)count/min
  • HRV (RMSSD)ms
  • HRV (SDNN)ms
  • Irregular Rhythm Events
  • Low Cardio Fitness Events
  • Low HR Events
  • Perfusion Index%
  • Resting Heart Ratecount/min
  • Walking HR Averagecount/min

Body

  • Basal Body TemperaturedegC
  • BMIcount
  • Body Fat %%
  • Body TemperaturedegC
  • Body Weightkg
  • Heightm
  • Lean Body Masskg
  • Waist Circumferencem

Respiratory

  • Blood Oxygen%
  • Respiratory Ratecount/min

Sleep

  • Sleep Apnea Events
  • Sleep Stages
  • Wrist Temperature (Sleep)degC

Nutrition

  • Caffeinemg
  • Carbohydratesg
  • Dietary Energykcal
  • Fiberg
  • Proteing
  • Sodiummg
  • Sugarg
  • Total Fatg
  • WatermL

Vitals

  • Blood Alcohol Content%
  • Blood Glucosemg/dL
  • Blood Pressure (Diastolic)mmHg
  • Blood Pressure (Systolic)mmHg
  • Fallscount

Workouts

  • Workouts

Other

  • Environmental SounddBASPL
  • Handwashing Events
  • Headphone AudiodBASPL
  • Loud Environment Events
  • Loud Headphone Events
  • Medication Doses
  • Mindful Minutes
  • Sound ReductiondBASPL
  • State of Mind
  • Time in Daylightmin
  • Toothbrushing Events
  • UV Exposurecount

Rendered at build time from the protocol's published vocabulary, catalog.json. Units are the canonical ones every sample is converted to before upload.

Looking for something not listed here? Every other document, the schemas and the code itself are in the repository. Browse the repository