Skip to content

Latest commit

 

History

History
74 lines (61 loc) · 5.3 KB

README.md

File metadata and controls

74 lines (61 loc) · 5.3 KB

openGym documentation

Pick the part that matches what you're doing. If you just have a question, try the FAQ first.

Using the app

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.

Hosting it

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.

Working on the code

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

Still stuck?

Ask on the Discord or in Discussions. If something in these docs was wrong or missing, that's worth an issue too.