Profile
Back to NewsBack
GitHub Trending 9 min
Reader Mode
umutkeltek/healthsave-observatory: Self-hosted health-data observatory: sync Apple Health, early wearable plugins, and Garmin/Samsung imports into a canonical TimescaleDB record; view baseline-linked findings and query a private API. Docker-ready, lo

umutkeltek/healthsave-observatory: Self-hosted health-data observatory: sync Apple Health, early wearable plugins, and Garmin/Samsung imports into a canonical TimescaleDB record; view baseline-linked findings and query a private API. Docker-ready, lo

HealthSave Observatory: your raw health data never leaves your host

Your Apple Health data, on a server you own.

A self-hosted dashboard for the HealthSave iPhone app.
Sleep, activity, blood tests and a whole year of records, each read against your own baseline.
No HealthSave account. Nothing leaves your server unless you choose.

Latest release CI License: Elastic 2.0 Docker images for amd64 and arm64 Download HealthSave on the App Store

Quick start  ·  Tour  ·  What's inside  ·  How it works  ·  Privacy  ·  Setup  ·  Docs

The Today screen: a recovery score of 69 marked Steady, and the latest sleep, resting heart rate, HRV, respiratory rate, steps and active energy readings, each with a small chart

Why Observatory

Yours to keep

Your readings live in a database on your own machine: a laptop, a NAS, a mini PC or a home server. There is no HealthSave account and no cloud service in between.
Read against you

Each number is compared with your own recent history, not with a population average. Every finding shows the data and the calculation behind it.
Nothing blended

Readings from two devices are never averaged into one number. Days with no data show as gaps instead of being filled in.

Free, with one optional paid plan

Everything in this repository is free to run, including backup, restore and updates, and nothing free will move behind a licence.

If you want your backups looked after, Observatory Care costs $99 a year or $9 a month. It adds encrypted backups on a schedule, copied to storage you choose (a NAS, S3 or Backblaze B2, through rclone), restore drills that prove a backup opens, and a one-command rollback after an update. The backups never reach HealthSave, and the licence is checked on your own server, offline. See Care · What it adds

Quick start

You need Docker Compose v2 on macOS, Linux, or Windows through WSL2.

npx healthsave

Pick Basic setup. It creates the passwords and an API key, then starts the default services. After that:

  1. Run healthsave pair. It prints your server's address, the API key and a QR code.
  2. Scan the QR code with the iPhone Camera. HealthSave opens with the address and key filled in. Tap Sync New Data.
  3. On the server, open http://localhost:4173. healthsave pair also shows the dashboard password.
Syncing to your own server is part of HealthSave Pro, a one-time purchase in the iPhone app. Observatory itself is free. Other ways to install are under Setup.

A look around

Sleep
Every night by stage, with consistency, efficiency and sleep debt.

Sleep screen: last night 7 h 27 min by stage, with consistency, sleep debt, efficiency and a 30-day duration trend
Activity
Steps, exercise, energy and walking heart rate next to your 7-day average.

Activity screen: steps, exercise minutes, active energy, resting and walking heart rate, cardiovascular load and a 30-day steps chart
Blood tests
Each marker against the range your lab printed and your own past results. Two labs stay side by side.

Labs screen: ferritin, hemoglobin, HbA1c and CRP results, each with its lab range, and a ferritin history across two labs
Year in Health
A year on one page: which days hold data, and which devices sent it. The share card shows no personal numbers unless you add them.

Year in Health screen: 312 of 319 days with data from 4 sources, a month-by-month calendar, and the round 2026 share card
Findings
Trends, outliers and links between signals, computed from your data, each with its numbers and limits.

Findings screen: HRV trending up over 30 days with effect size and significance, and steps moving with active energy over 90 days
Privacy
What stays on the server, what may leave it, and why.

Privacy screen: raw observations blocked, cloud egress off, prompt redaction on, and each data class with its rule
Explore
Build your own panels from any signals, then save the view or pin it to Today.

Explore screen: four chart panels for HRV, resting heart rate, walking metrics, and steps with exercise minutes
Compare
Two periods, sources or devices side by side, each kept as its own series.

Compare screen: heart rate for the last 30 days against the 30 days before

On your phone, too. Every screen works at phone width, in light and dark.

Today, Sleep, Labs and Year in Health on a phone-sized screen

All screenshots use a synthetic year made by scripts/seed_synthetic_year.py. None of it is a real person's data.

What's inside

Screens

| Group | Screens | |---|---| | Essentials | Today · Sleep · Activity · Labs · Findings · Data · Sources · Privacy | | Analyze | Explore · Genetics · Library · Compare · Relationships · Experiments · Timeline · Year in Health | | Manage | Integrations · Intelligence (the optional AI brief) · Settings |

Press ⌘ K (Ctrl K elsewhere) to jump to a screen or to any of about 190 signals.

Data in

| Source | How it connects | Status | |---|---|---| | Apple Health: Apple Watch, iPhone, and apps that write to it, such as Oura, Withings and many Garmin watches | HealthSave iPhone app | Ready | | Whoop, Amazfit / Zepp | Direct plugins (guide) | Early | | Garmin Connect, Samsung / Huawei Health | File importers (guide) | Ready | | Polar, Google Health | Direct plugins (plugins/sources) | Experimental | | Blood tests | healthsave labs import FILE.csv (guide); CSV and PDF upload with review in the web app | Ready; web upload in the next release | | Genetic evidence: 23andMe or Ancestry TXT/TSV, VCF | Matched against public ClinVar data on your own server (guide) | Next release | | Android Health Connect | HealthSave for Android, same data format | In development | | Any device, signed webhook | Generic ingest API (roadmap) | Planned |

"Next release" means the feature is on main but not yet in a tagged release. Installs follow tags.

Data out, only where you send it

  • Your own AI. healthsave mcp prints one line that connects Claude Code or Claude Desktop to your server, read-only. Ask "how did I sleep this year?" and it answers from your record. See Give your AI a body.
  • Home Assistant and MQTT. Publish the signals you pick as sensors. See Home Assistant & MQTT.
  • Grafana. Bundled, for your own SQL charts. See Grafana.
  • API and export. A read API under /api/v2, plus CSV and JSON export. See API.
  • A weekly brief, if you want one. A local model (Ollama) can summarize findings that were already computed. A cloud model is used only if you turn it on and agree, and it receives derived findings only. See Local LLM.

How it works

How it works: the HealthSave iPhone app and other wearables and files send data to the API on your server. The API stores it in TimescaleDB, one record with each device kept apart. A worker reads it, computes findings with plain statistics and writes them back; an optional local AI writes the brief. Observatory web and Grafana read the record. Home Assistant or MQTT, your AI client over MCP, and a cloud AI that gets derived findings only with your consent are reached only if you set them up.

The API stores every reading with the device it came from. The worker computes findings with plain statistics: trends, outliers, links between signals, and a recovery score. No AI model is needed for any of it. The web app, Grafana and the routes you add all read from that one record.

Privacy

| What | Where it goes | |---|---| | Raw readings | Stay in your database. The AI brief never receives them, local or cloud. | | Findings and summaries | Computed on your server. A cloud model sees them only if you turn cloud narration on and agree, and the prompt is redacted first. The Privacy screen lists what left and why. | | Home Assistant, MQTT, exports, MCP | Only the routes you set up, to the places you choose. | | HealthSave's own servers | Never receive your health data. Observatory needs no HealthSave account and has no analytics. |

More detail: Privacy and egress and Security.

The iPhone app also works without Observatory. Its dashboard, trends, and CSV, JSON and PDF export need no server, and it can write Home Assistant sensors directly. See healthsave.app.

Setup

Requirements

  • Docker Compose v2, installed and running.
  • macOS, Linux, or Windows through WSL2. On Windows, install Docker Desktop and turn on WSL integration for your Linux distro.
  • Node.js only if you use npm or npx. The shell installer does not need it.
  • No local Python install. Development uses Python 3.12; see Development.
Pre-built images for linux/amd64 and linux/arm64 are signed with cosign. It runs on a laptop, a VM, a NAS, a Proxmox VM or a home server; see Deployment.

Install

With Node.js:

npm i -g healthsave
healthsave onboard

No global install:

npx healthsave

Server or clean machine:

curl -fsSL https://raw.githubusercontent.com/umutkeltek/healthsave-observatory/main/install.sh | bash

Windows PowerShell (hands off to WSL2):

irm https://raw.githubusercontent.com/umutkeltek/healthsave-observatory/main/install.ps1 | iex

From a checkout:

git clone https://github.com/umutkeltek/healthsave-observatory.git
cd healthsave-observatory
./healthsave onboard

Every path opens the same control center: arrow keys and Enter. It covers setup, starting and stopping the stack, optional layers, checks, logs, and installing the CLI.

  • Basic setup (recommended first). Generates passwords and an API key, writes .env, creates config.yaml with local analysis on (anomalies, trends, correlations and recovery; no AI model needed), and starts the default services.
  • Advanced setup. Lets you choose the passwords, the API key, a local AI model (Ollama) and the optional layers. It checks your RAM and GPU and suggests a model.
Running setup again keeps your existing .env and config.yaml values.

What runs

| Service | What it does | Address | |---|---|---| | Observatory web | The dashboard | http://localhost:4173 | | API | Receives syncs from the iPhone app; serves the read API | http://:8000 | | Database | TimescaleDB, the one record | local only | | Worker | Computes findings from stored readings | n/a | | Grafana | Bundled SQL charts | http://localhost:3000 |

Optional layers stay off until you turn them on: local AI (healthsave up --ai), agents (--agents), an MQTT broker (--mqtt) and the Home Assistant bridge (--home-assistant).

Connect the iPhone app

healthsave pair shows the server address, the API key, a QR code (when qrencode is installed) and the dashboard password.

  • With the QR code: scan it with the iPhone Camera. HealthSave opens with everything filled in.
  • By hand: in HealthSave, open Settings → Server Sync, enter the address and the API key, then tap Sync New Data.
Use the server's network address, for example http://192.168.1.20:8000. Do not use localhost on the phone: there it means the phone itself. The app posts to POST /api/apple/batch; give it the base address only. Full guide: Connect HealthSave.

Check, update, back up

healthsave doctor        # platform, config, services and addresses
healthsave status        # what is running
healthsave update        # move to the newest release; takes a backup first
healthsave backup        # database, .env and config.yaml in one file
healthsave restore FILE  # takes a safety backup first

Everything above is free. Observatory Care, an optional licence, adds encrypted off-site backups, restore drills and one-command rollback.

To reach the dashboard away from home without opening a port on your router, use the Tailscale layer: Remote access. Behind your own proxy: Reverse proxy.

Scripts, CI and the CLI lifecycle

People should start with healthsave onboard or npx healthsave. Scripts and CI should use named commands:

set -euo pipefail
healthsave setup basic --no-input
healthsave doctor --json
  • npm package: healthsave. Global install: npm i -g healthsave, then healthsave onboard. No install: npx healthsave.
  • From a checkout: ./healthsave onboard. Put that checkout's command on your PATH with ./healthsave install-cli; remove it with ./healthsave uninstall-cli.
  • Uninstalling the npm package removes only the bootstrapper. Your checkout, containers, volumes, config and health data stay.
  • Homebrew formula template: packaging/homebrew/healthsave.rb.template.
  • More: CLI distribution.

Documentation

| Start | Use | Connect | Run | |---|---|---|---| | Overview | Observatory web | Capture sources | Deployment | | Zero to ready | Findings & Body Briefs | Home Assistant & MQTT | Backups & migrations | | Quick start | Grafana | Give your AI a body (MCP) | Remote access | | Connect HealthSave | Web vs Grafana | API | Participants | | Troubleshooting | Privacy and egress | Local LLM | Development |

Guides for the iPhone app, a metric reference and free in-browser tools are at healthsave.app: Observatory · export guide · metric reference · Apple Health XML to CSV converter, which runs in your browser.

Contributing: CONTRIBUTING.md · Security reports: SECURITY.md · Releases: CHANGELOG.md

License

The core server is licensed under the Elastic License 2.0: you can read, run, modify and self-host it, but not offer it to others as a hosted or managed service. The protocol, contracts and plugin SDK are licensed under Apache-2.0. See LICENSING.md.

Chat with me