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.
Quick start · Tour · What's inside · How it works · Privacy · Setup · Docs
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:
- Run
healthsave pair. It prints your server's address, the API key and a QR code. - Scan the QR code with the iPhone Camera. HealthSave opens with the address and key filled in. Tap Sync New Data.
- On the server, open http://localhost:4173.
healthsave pairalso shows the dashboard password.
A look around
|
Sleep Every night by stage, with consistency, efficiency and sleep debt.
|
Activity Steps, exercise, energy and walking heart rate next to your 7-day average.
|
|
Blood tests Each marker against the range your lab printed and your own past results. Two labs stay side by side.
|
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.
|
|
Findings Trends, outliers and links between signals, computed from your data, each with its numbers and limits.
|
Privacy What stays on the server, what may leave it, and why.
|
|
Explore Build your own panels from any signals, then save the view or pin it to Today.
|
Compare Two periods, sources or devices side by side, each kept as its own series.
|
On your phone, too. Every screen works at phone width, in light and dark.
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 mcpprints 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
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
npmornpx. The shell installer does not need it. - No local Python install. Development uses Python 3.12; see Development.
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, createsconfig.yamlwith 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.
.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:// |
| 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.
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, thenhealthsave 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.