Model or dataset
CodeWithCJ/SparkyFitness avatar
CodeWithCJ/SparkyFitness

SparkyFitness: a self-hosted household tracker with a non-commercial licence

SparkyFitness: Built for Families. Powered by AI. Track food, fitness, water, and health — together.

6,780 stars470 forksTypeScriptNOASSERTION

At a glance

What is it?
SparkyFitness bundles nutrition, exercise, sleep, fasting and body metrics into one self-hosted server with native mobile apps and a family permission model. The README calls it source-available rather than open source, and that distinction should shape who adopts it.
Who is it for?
Adopt SparkyFitness if you already run Docker Compose on hardware you control, want one database for a household, and can live with a licence that the README describes as non-commercial and requiring permission for commercial use. Do not adopt it if you need a permissive OSI licence, or if you want the software itself to measure sleep stages, HRV or blood glucose, since the README states those are imported from a watch, phone or meter and only stored and charted here.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • CodeWithCJ/SparkyFitness6,780 ★ · +950
Star history
Repository2026-09-132026-11-13
CodeWithCJ/SparkyFitness5.8k6.8k

950 Stars in the last 61 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The problem SparkyFitness is aimed at

Most consumer fitness tracking splits across subscriptions. The README's own comparison page argues that covering nutrition, strength, sleep, fasting, cycle and medication tracking means three or four separate subscriptions per person, and that even then no single report spans them. SparkyFitness answers that by putting the data in one server you run, with multiple user profiles and family access on top. The target user is a household rather than an individual. The README lists multiple user profiles and family access as a core feature and the comparison table claims seven granular permissions, which is a different design point from a single-account tracker that happens to support a second login. The secondary audience is anyone who wants the data to stay on their own infrastructure. The README states the project stores and manages health data on infrastructure you control, without relying on third party services.

What actually runs: server, web frontend, two mobile apps

The repository describes four components: a backend server that provides the API and data storage, a web-based frontend, native mobile apps for iOS and Android, and companion apps for Apple Watch and Wear OS. The primary language is TypeScript, which is consistent with a shared API and web layer, though the README does not break down which parts of the mobile apps are native versus shared. Data flow is pull-then-store. Integrations sync activity such as steps, workouts and sleep, plus health metrics like weight and body measurements, into your SparkyFitness server. That wording matters: the README's footnote states that sleep stages, HRV and blood glucose are imported from your watch, phone or meter, and that SparkyFitness stores, analyses and charts them rather than measuring them itself. So the server is a store and a reporting layer, not a sensor. The integration list is long and mixed in character: Apple Health and Google Health Connect for phone-collected data, Fitbit, Garmin Connect, Withings, Polar Flow, Oura and Strava for devices and services, OpenFoodFacts, USDA, Fatsecret, Nutritionix, Swiss Food Database, Mealie, Tandoor and Norish for food, and Wger and Free Exercise DB for exercises. Two entries carry caveats in the README itself: Strava is marked partially tested, and Yazio is noted as using an unofficial API. An unofficial API can break without notice, and the project is telling you so.

Getting a server up with Docker Compose

The README offers two installation paths and documents the self-hosted one first. The commands it gives are a folder creation followed by a compose file download: mkdir sparkyfitness && cd sparkyfitness. The next step downloads docker-compose.yml with curl, and a third sets up a .env configuration, either generated in the browser with secure keys or from a minimal template of five values. The second path is a cloud option for non-technical users, deploying a hosted instance through third-party providers such as PikaPods or Zenith. On authentication, the core feature list names OIDC, TOTP, Passkey and MFA, so a self-hosted deployment can sit behind your existing identity provider rather than local passwords alone. That is the part of the setup worth planning before you invite family members, since the comparison table claims seven granular permissions for family sharing.

The licence is the first thing to read, not the last

The repository metadata reports the licence as NOASSERTION, and the README is unusually direct about why: SparkyFitness is source-available, not open source, the licence is non-commercial, and commercial use requires permission. That single sentence changes the adoption decision more than any feature on the list. If you are an individual running this for your household, the stated terms appear to cover you. If you are a company wanting to offer this to employees, a gym wanting to host it for members, or a developer wanting to build a paid product on the API, you are outside what the README describes and need to seek permission. This is not a legal opinion and the LICENSE file is the authority; the point is that the README's own framing contradicts the assumption many engineers make when they see a public repository with a Docker Compose file.

The AI features are beta, and the README says so

SparkyAI is described as an optional conversational interface for logging data and reviewing progress. The documented capabilities are logging food, exercise, body stats and steps through chat, uploading food images for automatic meal logging, and retaining conversation history for follow-ups. The README labels the whole set as beta, twice: once in the section heading and once in a note. It also advertises an MCP server and bring your own LLM, which means the model is your choice and presumably your API key and your cost. The honest reading is that chat-based logging is a convenience layer over the same database the manual entry path writes to, and that its reliability is not something the README makes any claim about. Image-based meal logging in particular depends on the model recognising the food and on a matching entry existing in whichever food database you have connected. If you are evaluating SparkyFitness for the AI, you are evaluating a beta feature whose accuracy the project does not quantify. If you are evaluating it for the tracking, the AI is a feature you can ignore, and the core feature list does not depend on it.

Where it fits badly, and what to use instead

SparkyFitness is the wrong tool if you want a permissively licensed codebase you can modify and redistribute, because the licence is non-commercial by the README's own description. It is also the wrong tool if you do not want to run a server. The second installation path is a hosted instance on third-party cloud providers rather than your own server, and the mobile apps are clients to that server. For the self-hosted strength-training case specifically, wger is the obvious alternative and the README's own table places it there: wger is marked as self-hosted with your data staying yours, and as not supporting wearable or health-platform sync, while SparkyFitness claims eight or more services. The difference in approach is scope. wger is a workout and gym management tool that grew a nutrition side; SparkyFitness is a general health record that includes strength work among nutrition, hydration, sleep, fasting, mood and body measurements. If your need is programming sets and tracking lifts, wger's narrower focus is a better match and its licence situation is different. If your need is one place where a family's food, weight, steps and sleep land together, the breadth is the reason to pick SparkyFitness. Note that the comparison table is written by the project being compared, and the README says so explicitly, so use it as a map of categories rather than as a verdict.

Upgrade cadence and what it costs you to stay current

The release history shows v1.9.0 on 21 October 2026, v1.10.0 on 29 October, and v1.11.0 on 30 October, with the last push on 4 October. Three releases in about ten days is a fast cadence for a self-hosted service. That is good for fixes and bad for operators who dislike touching a working deployment. Because the documented install is Docker Compose, the upgrade path is presumably pulling a new image and restarting, so check the documentation site for the migration policy, whether database schema changes are applied automatically on startup, and whether downgrades are supported. Those are the questions to answer before you put family data in it. The comparison table claims CSV import and free data export, which is the mitigation: if you can export, a bad upgrade is recoverable rather than terminal. Verify that the export actually covers the tables you care about, and take one before the first upgrade rather than after. Running cost is your hardware, your electricity and, if you enable SparkyAI, your model provider's bill. There is no subscription described.

Editorial conclusion

Adopt SparkyFitness if you already run Docker Compose on hardware you control, want one database for a household, and can live with a licence that the README describes as non-commercial and requiring permission for commercial use. Do not adopt it if you need a permissive OSI licence, or if you want the software itself to measure sleep stages, HRV or blood glucose, since the README states those are imported from a watch, phone or meter and only stored and charted here. Before committing, verify the licence text in the LICENSE file against your intended use, confirm that your specific wearable appears in the integration list rather than relying on the count, and check whether the mobile apps are distributed through the app stores or built from the repository.

Frequently asked questions

Can SparkyFitness be self-hosted?

Yes. The project describes itself as a self-hosted, privacy-first alternative to MyFitnessPal, Flo, Hevy and Shotsy, and its documented install path is a Docker Compose flow that fetches a docker-compose.yml with curl. It ships a backend server, a web frontend and native mobile apps.

What is a self-hosted alternative to MyFitnessPal?

SparkyFitness presents itself as that alternative. It tracks nutrition, exercise, hydration, sleep, fasting, mood and body measurements, stores that data on infrastructure you control, and marks no subscription and no ads as supported.

How do I install SparkyFitness?

The documented route is Docker Compose. You create a folder with mkdir sparkyfitness && cd sparkyfitness, then download docker-compose.yml with curl. The repository also carries docker/, helm/, umbrel/ and nix/ directories for other deployment shapes, and the alternative route is a hosted cloud instance through third-party providers.

What makes SparkyFitness different from wger and other trackers?

wger is listed as one of its integration sources as well as a comparison column, where SparkyFitness marks itself standout for self-hosting, for combining nutrition, strength, sleep and fasting in one place, and for an MCP server with bring your own LLM. The grid notes it was written by the project being compared.

Official sources

  1. CodeWithCJ/SparkyFitness on GitHub
  2. Issues
  3. Project website
  4. README
  5. Releases
Community

Where developers are discussing it

Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 0 in the last 30 days; newest first.

Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/codewithcj-sparkyfitness.svg)](https://hysenlabs.com/projects/codewithcj-sparkyfitness)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/codewithcj-sparkyfitness.svg)](https://hysenlabs.com/projects/codewithcj-sparkyfitness)

Was this useful?