openGym has two sister apps: openNutrition (food, in private beta: the repository is not public yet) and openRunning (runs and rides, planned, working name). They stay separate apps with separate data. openGym only ever reads from them, only after you link them, and every link can be undone from both sides.
This page is the contract: what openGym reads, from where, and what each sister app has to
serve. The openGym side is in frontend/src/lib/sister-nutrition.js (openNutrition) and
frontend/src/lib/activities.js (runs and other sport, from any source).
| Where in openGym | Off by default | Network | |
|---|---|---|---|
| openNutrition link | Settings → Integrations → Sister apps → openNutrition | yes (nothing until linked) | yes |
| Nutrition in the performance report | Stats / History → Performance report (PDF), section "Nutrition" | linked + switch "Performance report" | cached |
| Nutrition in the month story | Stats → Your month, card "Fuel" | linked + switch "Your month" | cached |
| Fasting window on Home | Home, under today's session | linked + switch "Fasting window on Home" | cached |
| Runs and matches from Apple Health / Health Connect | Settings → Integrations → Apple Health / Health Connect → "Runs, rides and matches from other apps" | yes | no (on the phone) |
| Sport in the week streak | Settings → Look & Home → "Sport counts for the streak" | yes | no |
| Sport in the recovery map | Stats → Muscles, Home recovery hint | on whenever there are activities (S.activityRecovery === false turns it off) |
no |
| Sport days from imports | Settings → Data → Import (Apple Health export.xml workouts; Hevy / Strong sessions that were only sport) | the import itself is the opt-in | no |
| Sport in the calendar and History | Stats → calendar (blue dot), History rows, a day's sheet ("Log an activity") | shows whatever came in | no |
openGym Offline (the Android flavour without the INTERNET permission, lib/build-caps.js)
cannot reach openNutrition, so the openNutrition card belongs in OFFLINE_OFF_CARDS
(card id opennutrition). The health-store read and imports work offline.
Sport that is not a gym workout is an activity, stored per session in the profile document:
S.activities = {
'<id>': { d: '2026-11-06', sport: 'run', min: 42, km: 8.1, at: 1762412400000,
title: 'Morning loop', note: '', src: 'hc' | 'ah' | 'import' | 'manual' | 'or', _ts },
}sportis one ofrun ride swim hike row ski football racket ball climb fight yoga dance other.- A removal is a stamped empty entry (
{ _ts }), merged per key likerecoverySessions(lib/sync-merge.jsandapi/sync-stamps.jsSTAMPED_MAPS). An id that came from a health store or a file is derived from the source's own id, so reading it again never adds a second one and a removed one is never brought back. - Activities never enter
S.workouts: no sets, no volume, no records. - Streak: counted only with
S.activityStreak === true(the shared walk,api/coach/core/streak.js, so a trainer sees the same number). - Recovery:
activityStimuli(S)turns each activity of the last 30 days into hard-set equivalents per muscle (SPORT_LOAD: per 30 minutes; football 3 sets spread over quads, hamstrings, calves, glutes, adductors and hip flexors, a run 3 sets mostly calves and quads, yoga half a set), whichfatigueOf(..., { activities })adds with the muscle's usual half-life and the per-session cap of 12 sets. - Scoped tokens and the MCP server see them under the
workoutscategory (api/tokens.js).
openNutrition already links to openGym: openGym shows a pairing code (Settings → Account →
"Pair the mobile app"), openNutrition redeems it at POST /api/pair/redeem and keeps the token
server side. The other direction works the same way, with the roles swapped and a narrower token:
-
openNutrition, Settings → Connected apps → Link openGym: shows an 8-character code, valid 10 minutes, for the scope
summary:read. -
openGym, Settings → Integrations → Sister apps → openNutrition: the openNutrition address (guessed as
nutrition.<your domain>) and the code. -
openGym redeems it:
POST /api/v1/integration/pair/redeem Content-Type: application/json { "code": "GYM12345", "app": "opengym", "scopes": ["summary:read"] }
{ "token": "on_…", "scopes": ["summary:read"] }A wrong or expired code answers 401. Rate limited like any sign-in.
-
openGym reads the summary once with the token before it keeps anything, then keeps the token in the phone's secure storage (the browser's storage on the web), never in the synced profile or a backup. Each device links on its own.
Today, before step 1 exists: openNutrition's Settings → Connected apps can already create a
personal token with summary:read. Pasting that on_… token into the same field works the same,
so the link is usable now against any openNutrition that serves the summary.
GET /api/v1/integration/summary?from=YYYY-MM-DD&to=YYYY-MM-DD
Authorization: Bearer on_…The schema opennutrition.summary.v1 as openNutrition serves it today
(docs/integration-opengym.md in openNutrition): days[] with date, energy, protein,
carbohydrate, fat, complete, targets: { energy, protein }. openGym uses energy, protein
and the targets, and says so in the report when a day was complete: false.
Two additive fields openGym reads when they are there (v1 stays v1: older openNutrition simply does not send them and the cards leave those lines out):
-
days[].proteinMeals: how many meals that day reached openNutrition's protein-meal threshold (its "Protein meals" dots, 0.4 g per kg body weight), an integer 0 to 12. openGym never guesses it from the day's total. -
fasting: the fasting timer, or absent when it is off:"fasting": { "enabled": true, "goalHours": 16, "startedAt": "2026-11-03T20:00:00.000Z", "last": { "start": "2026-11-02T20:00:00.000Z", "end": "2026-11-03T12:00:00.000Z" }, "window": { "opensAt": "2026-11-03T12:00:00.000Z", "closesAt": "2026-11-03T20:00:00.000Z" } }
startedAtis the running fast (null when none runs).windowis optional: without it openGym takes the eating window as the end of the last fast plus24 - goalHourshours.
How often: when a screen that shows it opens and the last read is older than 30 minutes, the report sheet for its range, the month story for its month. The answer is cached on the device (400 days at most). The Home line only trusts an answer younger than six hours.
The phone apps ask from native code (lib/capacitor-fetch.js nativeFetch): no CORS involved.
The web app runs on openGym's own origin and needs openNutrition to allow it on the
integration routes:
Access-Control-Allow-Origin: https://gym.example.com (from an allow-list, never *)
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Methods: GET, POST, OPTIONS
Vary: Origin
for OPTIONS and the real request on /api/v1/integration/summary and
/api/v1/integration/pair/redeem, with the allow-list from openNutrition's environment
(INTEGRATION_ORIGINS, defaulting to its own OPENGYM_URL).
| Answer | openGym says |
|---|---|
| network error, CORS refused | could not reach it (check the address) |
| 401 / 403 | revoked: link again |
| 404 on the redeem route | this openNutrition has no codes yet: paste a token |
| 429 | slow down |
anything not opennutrition.summary.v1 |
not openNutrition |
Unlinking in openGym forgets the token and the cached days. Revoking the token in openNutrition ends access; openGym shows "Needs attention" on the card and keeps the old numbers until unlinked.
api/sources/nutrition.js (the trainer's nutrition category, NUTRITION_SOURCE=opennutrition)
reads the same summary. Its cleanDay reads both openNutrition's names (energy, carbohydrate,
targets) and its own older ones (kcal, carbs, target). A server-side link (so the trainer
dashboard gets the member's token) is not built: the device link above keeps the token on the
phone on purpose.
openRunning does not exist yet. Until it does, runs, rides and matches reach openGym through the
phone's health store (any app that writes workouts there: Strava, Garmin, Apple Workout, Runna,
Polar, Zepp) and through imports. When openRunning is built, it can feed the same activities
directly, with this contract. Its concept (openStride, KONZEPT.md) plans one account and one
server for all three apps; the pairing below is the fallback for two different servers or a
phone without one.
The same as openNutrition, scope activities:read:
POST /run/api/v1/integration/pair/redeem { code, app: 'opengym', scopes: ['activities:read'] }→{ token: 'or_…', scopes }.- On a shared server with a shared login, no pairing: openGym reads with its own session once the user allowed it in openRunning's settings (consent stays explicit and revocable).
GET /run/api/v1/integration/activities?since=<cursor>
Authorization: Bearer or_…{
"schema": "openrunning.activities.v1",
"cursor": "opaque, for the next call",
"activities": [
{ "id": "uuid", "start": "2026-11-05T06:30:00Z", "end": "2026-11-05T07:12:00Z",
"sport": "run", "title": "Morning loop", "km": 8.1, "elevationM": 85,
"load": { "trimp": 72 }, "muscles": { "calves": 0.8, "quadriceps": 0.6 },
"deleted": false }
]
}sportuses openGym's names above (run,ride, …); anything else isother.load.trimp(optional) scales the recovery load instead of the minutes;muscles(optional) overrides openGym's ownSPORT_LOADfor that activity.deleted: trueremoves it in openGym too (stamped, so it stays gone).- No GPS track, no heart-rate stream, no photos: openGym needs the day, the time and the effort.
- openGym stores each as an activity with
src: 'or'and the idor<uuid>. When the same session also arrives through the health store, openRunning's copy wins (openRunning writesclientRecordId/HKMetadataKeySyncIdentifier=openrunning-<uuid>so openGym can match it).
openGym opens an activity in openRunning with https://opengym.ch/r/a/<id> (KONZEPT.md 7.2);
without the app installed, the link goes to the web version of the instance.
Out of openGym's scope here: openRunning reads strength days the way openNutrition does today
(an openGym pairing code, POST /api/pair/redeem, then /api/data), better with a scoped
ogt_ token (docs/API_TOKENS.md, category workouts, read only).