Pick the part that matches what you're doing. If you just have a question, try the FAQ first.
| Guide | Read it when |
|---|---|
| FAQ | You have a quick question: iPhone, cost, where your data goes, AI, the exercise media |
| Modules | You want a leaner app (just training, or training and body), or wonder what switching a module off hides and keeps |
| Phone app | You want the iPhone app, the Apple Watch or the Android APK, or to connect the app to your own server |
| Wear OS watch | You want openGym on a Galaxy Watch, Pixel Watch or another Wear OS watch, or you work on the watch app |
| Watch sync protocol | You work on how the Apple Watch and Wear OS apps keep in step with the phone (outbox, acks, the end of a workout) |
| Garmin watch | You want openGym on a Forerunner, fēnix, Venu, Instinct or another Garmin, or you build and publish the Connect IQ app |
| Zepp OS watch | You want openGym on an Amazfit (Zepp OS) watch, or you work on that watch app or the watch relay |
| Importing data | You're coming from FitNotes, Strong, Hevy or Apple Health, or sharing a plan with someone |
| AI coach | Your instance has the coach switched on and you want to know what it sees and can change |
| Integrations | You want Apple Health, Health Connect, your watch or scale, or a webhook to Home Assistant, n8n or ntfy |
| Backup to WebDAV | You want a daily copy in your own Nextcloud or WebDAV folder, and to restore it on a new phone |
| Calendar feed | Your planned sessions (and finished workouts) should show up in Apple, Google or Outlook calendar |
The live demo is the real app with example data, nothing to install.
| Guide | Read it when |
|---|---|
| Self-hosting | You're setting up an instance. Start here: running it, passkeys and HTTPS, users, backups, updates, troubleshooting |
| HTTPS at home | You want valid certificates on your LAN without exposing the server to the internet |
| On a Mac | You want to run it on a Mac at home, with Colima instead of Docker Desktop and Tailscale for HTTPS |
| Kubernetes | You run a cluster instead of Docker Compose |
| AI coach | You're deciding whether to turn the coach on, and with which provider |
| MCP server | You want Claude Desktop, Cursor or another AI client to read your training history |
| MCP over HTTPS | Claude, ChatGPT or another assistant should use openGym's tools at /mcp (sign in with openGym, or a token) |
| Routines library index | You want to publish routines the AI Coach can suggest and import |
| API tokens | A program (an assistant, a planner, a script) should see or change only some of your data |
| Integrations | You're turning on webhooks (INTEGRATIONS), or letting them reach your home network |
| Trainers | You're turning on gyms, gym leads and trainers (TRAINERS), or want admins to see training data again (ADMIN_DATA_VIEW) |
| NixOS | You run NixOS and want openGym native: flake packages and a NixOS module, no Docker |
| Security | You host it for other people, or want to report a vulnerability |
All settings live in .env; .env.example explains each one, and the
README has the full table.
| Guide | Read it when |
|---|---|
| Contributing | Before your first pull request: setup, guidelines, what CI checks |
| Architecture | You want the map: how the app, server, phones and watch fit together, with diagrams |
| App stores and releases | You're shipping a release: the APK, Google Play and the App Store |
| scripts/ | You want to know which build script does what |
| CLAUDE.md | The same project context in the form Claude Code sessions start from |
| HTTP API | You're touching routes; the OpenAPI spec is the source of truth |
| Roadmap | You want to know what's planned and where your idea fits |
| Changelog | You want to know what changed in a release |
Design notes for specific features, kept next to the code they describe:
| Note | Covers |
|---|---|
| Set types | Drop sets and rest-pause: the set-row model and how totals are counted |
| Workout views | The cards, list and compact layouts of the workout screen |
| Combine routines | Spec for running more than one routine in a session |
| Fatigue and sets | How hard sets feed the fatigue map and its recovery time per muscle |
| Sister apps | openNutrition and openRunning: the read-only link, activities (runs, matches) and the pairing contract |
Ask on the Discord or in Discussions. If something in these docs was wrong or missing, that's worth an issue too.