Skip to content

Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.

3.4 KB
Raw Blame

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
Phone app You want the iPhone app, the Apple Watch or the Android APK, or to connect the app to your own server
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

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
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

Still stuck?

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