Build with your data

Your ring knows your sleep, your watch your heart rate, your phone your steps, and each keeps its share in its own app. Open Health Sync brings them into one place you run yourself, in the same units and the same shape. From there, a useful tool is a few lines of code.

The recipes/ folder holds small tools that do one thing each. They are single Python files with no dependency: copy one, run it, change it.

New to this? Learn by building walks you through them in seven short projects, from a first sync to a server of your own.

For you, or for the people you build forCopy Anchor Link

For yourself. One instance on a laptop, a home server or a Raspberry Pi holds your accounts and nobody else's. The recipes run against it in a few seconds.

For developers. The recipes call the same REST API your product would, with the same tenant key. Each one is a worked example of an endpoint: reading a list page by page, choosing between two devices that report the same day, an export, a token for an agent. Start from the one closest to your idea.

Set up in five minutesCopy Anchor Link

1. Start an instance with the quickstart (Docker Compose, about two minutes).

2. Make it yours. This creates a personal tenant, a user named me and an API key, and writes them where every recipe looks for them:

   Copy Text

   docker compose --env-file .env -f deploy/docker-compose.yml exec -T ohs \
     /ohs admin personal setup > ~/.ohs.env
   chmod 600 ~/.ohs.env

   The file holds three lines, OHS_URL, OHS_KEY and OHS_USER. Running the command again keeps the same user and prints a new key (earlier keys keep working until you revoke them). For a second person in the household, add --person alex and write to another file; point a recipe at it with OHS_ENV_FILE=~/.ohs-alex.env.

   Running the recipes on another computer than the instance (a Raspberry Pi or a home server)? The compose setup publishes the API on 127.0.0.1 only: set OHS_HTTP_BIND=0.0.0.0 in .env (or put a reverse proxy in front, see self-hosting), then change OHS_URL in the file to the instance's address.

3. Bring your data in. Connect an account (set its keys on the server first, see Connectors):

   Copy Text

   python3 recipes/connect.py oura

   For an iPhone, export everything from the Health app (your picture, Export All Health Data) and import the zip with the ohs binary, through an upload token minted for me:

   Copy Text

   set -a; . ~/.ohs.env; set +a
   export OHS_TOKEN=$(curl -s -X POST "$OHS_URL/v1/users/$OHS_USER/tokens" \
     -H "Authorization: Bearer $OHS_KEY" -d '{"scopes":["upload"]}' | jq -r .token)
   ohs import apple-health export.zip

   Details in Apple Health.

4. Run a recipe:

   Copy Text

   python3 recipes/sleep-report.py

The key in ~/.ohs.env reads everything on the instance: keep the file private, and use the AI recipe to hand out a narrower, read-only token instead.

Write your ownCopy Anchor Link

Every recipe starts with the same block of about 60 lines: it reads ~/.ohs.env, calls the API and follows the pages of a list. Below it, a tool is usually one loop:

for night in records("sleep", start="2026-09-01"):
    print(night["bedtime_start"], night["total_sleep_seconds"] / 3600, night["provider"])

records(name, **filters) reads any list of the API: samples (with type, such as heart_rate or step_count), sleep, workouts, daily, nutrition, category-samples. Every record carries provider, the app it came from, so a tool can pick one device or compare them. Quantity names and units are in the data model.

Made something useful? Open a pull request that adds it to recipes/ with a page here.