A history longer than the phone’s
HealthKit keeps everything, but only as long as you keep the device and the backup chain intact. A server gives you a second, queryable copy that you control, with compression and no retention policy.
Local-first · MIT licensed
Your Apple Health data, read where it already lives.
The Helsa app reads HealthKit on your iPhone, does its analysis on the device, and by default your health data never leaves the phone. Sending it anywhere is a switch you turn on — and when you do, you type in your own endpoint. This is the server that endpoint can point at.
Go API · ingestion worker · TimescaleDB · web dashboard · deployment recipe. Fork it, or replace it with your own that speaks the same API contract.
The app is in closed testing
Helsa is not on the App Store yet. The iPhone app is in a TestFlight round — invitation only, and the invitations go to people the author already knows. There is no public link, and this site is not one.
What you can use today is the server: it is MIT licensed, it is documented here, and its API contract is the thing to implement if you would rather write your own client. The contract can still move while the app is in testing; a breaking change is described in the commit that makes it, because nobody outside depends on a deprecation window yet.
Not a medical device
Helsa is a hobby project for looking at your own fitness data. It is not a medical device, it is not for diagnosis, treatment, or monitoring of any medical condition, and its output must not be used to make health decisions. It comes with no warranty of any kind. See the full disclaimer.
On the phone
The part that works without any of this
Everything below runs on the device: 120 metrics, sleep stages, workouts, hydration, and a journal of what you felt at the time. The screenshots are taken from the running app, and the person in them does not exist.
What it is
Two layers, and the second one is optional
Always
iPhone — the Helsa app
HealthKitanalysiswhat you see
HealthKit is the store and the analysis runs on the device. This works fully offline, with no server at all.
Optional, opt-in, and you type the URL. Mutual TLS plus a device token.
Only if you want it
Your server — this repository
CaddyAPIRabbitMQworkerTimescaleDB
Long-term history, a web dashboard on your LAN or VPN, exports, and daily summaries for Home Assistant.
The phone is the only writer. Every other surface — the web dashboard, an iPad, Home Assistant — reads from the server. That asymmetry is not a preference: HealthKit has no cloud API, so the device holding the data is the only thing that can upload it.
Why you might want it
Four reasons to run a server
A browser view
Apple Health is an iPhone app. There is no official web view of your own data. The dashboard here is one.
Automation
Daily summaries into Home Assistant over MQTT, with discovery — including the sync-freshness sensor that tells you when the pipeline has quietly stopped.
SQL
It is a Postgres database with your data in it. Ask it whatever you want.
Why you might not
You probably do not need this
If you just want to look at your numbers on your phone, you do not need any of it. Run the app without a server. That is the intended default, and the project is built so that the default is the complete experience for a single device.
Running a server means running a server: TLS certificates that expire, backups that must be tested, a port on your router, and a database that is now your responsibility. The rest of these pages are honest about that cost.
Boundaries
What it deliberately does not do
- Medical advice, scoring, or diagnosis
- Out of scope, permanently. It reports numbers you already have.
- A hosted service
- Nobody operates a Helsa cloud. There is no sign-up. Your data goes to your machine or nowhere.
- Health data in iCloud
- HealthKit is the store, and Apple already syncs and backs it up. The app keeps no second copy, so there is nothing to put in iCloud. Only app settings sync.
- Keep its own copy of what you type
- What you enter goes into Apple Health, not into a Helsa database: the water you log, and the symptoms and mood you record. Everything measured — steps, heart rate, sleep — is read-only, and your Apple activity goals are never touched.
- Multiple users, sharing, family views
- Single user by design. The schema keeps a user_id column so the door stays open, but nothing multi-tenant is built or tested.
- Telemetry or analytics
- The app and the server collect nothing about you. There is no identifier, no crash pipeline, no phone-home.
- LLM-generated health insights
- The /insights endpoint is rule-based and explainable: rolling averages, z-scores, Pearson correlation. Each rule has a data minimum, and stays silent below it.
- A packaged mobile app
- The iOS app is closed source and not distributed here. This repository is the server side.
Where to go next
The documentation
Getting started
Bring the stack up locally with Docker Compose, issue a device token, verify a first sync. Nothing is exposed to the internet.
Deployment
TLS, mutual TLS with a private CA, the reverse proxy, backups and restore, and a hardening checklist. Read before you open a port.
API
The contract: what /v1/ingest accepts, what the read endpoints return, and the conventions — UTC, SI units, cursors — that apply everywhere.
Integrations
Home Assistant over MQTT with discovery, plus a REST fallback. Daily summaries only, and the page explains why that limit matters.
Status and stability
The OpenAPI document in backend/api/openapi.yaml is the source of truth; the server, the app and the web client all generate from it. It is now a public interface, so breaking changes have a cost — but the version is 0.x and the project is one person’s hobby. Pin what you depend on.