Trace Every Bite — A self-hosted personal nutrition tracker built for privacy and full data ownership.
NutriTrace runs as a single Docker container on your own hardware, with a PWA for the browser and a native Android app for your phone. No accounts on external services, no data leaving your network, no subscriptions.
- Self-hosting is and will remain free. The server, PWA, and source code will never be paywalled.
- No trackers, no analytics, no telemetry. NutriTrace doesn't phone home — your usage is invisible to anyone but you.
- Your data stays on your hardware. No central server, no cloud sync that can read it; nothing leaves your network unless you opt into a third-party integration (OFF, USDA, Fitbit, etc.).
- Open source under AGPL-3.0. Every line that touches your data is readable.
- Daily food diary with configurable meals (Breakfast, Lunch, Dinner, Snacks, or fully custom)
- Quick-add foods, meals, and recipes with portion scaling — food notes (e.g. "1 serving = 150g cooked") are surfaced at add time
- Nutrition bar with macro summary and per-meal breakdowns
- Body stats tracking (weight, measurements, and more) with customizable fields
- Water intake tracking with configurable containers and daily goal
- Long-press (mobile) or right-click (desktop) for item edit/move/delete actions
- Per-meal ⋮ menu: copy or move all items to another meal, copy the meal to another date, save the meal to your library, or clear it
- Per-day free-text notes (e.g. "felt bloated after lunch", "post-workout") — toggleable, with an indicator on dates that have a note
- Personal food database with photos, barcodes, categories, and custom labels
- Barcode scanner (camera) for quick food lookup via Open Food Facts
- Meal and recipe builder with drag-to-reorder ingredients
- Proportional nutrition scaling when editing serving size
- Import foods from Open Food Facts, USDA FoodData Central, or Mealie (recipe manager)
- Charts for any tracked nutrient or body stat over time
- Bar and line chart modes; average, trend, and goal overlay lines
- Configurable date ranges
- Calorie and nutrient goals with template support
- Wizard calculates TDEE (Mifflin-St Jeor) and water goal from body stats and activity level
- Light / dark / system theme
- Custom accent color (presets or full hex color picker)
- Configurable navigation style (bottom bar, sidebar, or both)
- Custom nutriment visibility and display order
- Custom body stat fields and display order
- Date and time format options (US / ISO / EU / Natural)
- Unit system: weight, height, length, distance
- Optional user management — runs perfectly as a single-user app with no login required
- Admin can invite additional users via email or shareable link
- All data is scoped per user
- Configurable session timeout
- Optional AI chat assistant for nutrition questions and logging help
- Supports Claude (Anthropic), OpenAI, and Google Gemini — bring your own API key
- Tool use across all providers: Trace can query your real diary (with day notes + per-item notes), saved meals/recipes library, wellness metrics, body composition, workouts, and goals — no hallucinated numbers
- Optional Goal Insights mode: proactive analysis of actual intake vs targets with evidence-based suggestions
- Full backup: ZIP archive of all database tables + uploaded images, stored on the server
- Download backups to your device or restore from a previously saved backup
- Upload and restore from a backup file taken on another instance
- Portable JSON export/import (foods, meals, diary, settings — no images)
- Local Full Backup (Android local-only mode): self-contained
.zipwith embedded image files for phone-to-phone transfer without a server - CSV diary export
- Import from Waistline (Android nutrition app)
Smart Log is an experimental feature that lets you log food by pressing and holding the Trace button on any page and saying what you ate. The AI parses your sentence and matches each item against your saved foods, meals, recipes, or yesterday's diary.
- Settings → AI Assistant → enable the assistant and configure a provider key (Claude, OpenAI, or Gemini).
- In the same section, enable the Smart Log toggle (Experimental).
- Grant microphone permission the first time you use it.
- Press and hold the Trace floating button (any page) for ~½ second.
- The robot face morphs to a microphone, the FAB turns red, you'll hear a short beep and feel a haptic buzz.
- Speak what you ate.
- Release the button to commit. Slide your finger off the FAB before releasing to cancel.
- The Smart Log review modal opens with the parsed items already matched. Edit quantities, swap matches, change meal slots, then tap Add to Diary.
| Source | What it matches | Example phrases |
|---|---|---|
| Foods (default) | Single foods from your library, then Open Food Facts | "2 eggs", "a slice of toast", "Greek yogurt" |
| Saved Meals | Multi-ingredient meals you've built in MealEditor | "my chicken caesar salad meal", "the pasta carbonara meal", "for lunch I had my morning bowl meal" |
| Saved Recipes | Recipes you've saved (with is_recipe: 1) |
"my chicken stir fry recipe", "made the pasta carbonara recipe", "from my lasagna recipe" |
| Yesterday's diary | Copy items from yesterday's matching meal slot | "same as yesterday for lunch", "yesterday's breakfast", "repeat yesterday's dinner", "what I had for breakfast yesterday" |
| Water | Adds to your water log (not the food diary) | "drank a glass of water", "500ml of water", "had my protein shaker", "two cups of water" |
The trigger words "meal", "recipe", and "yesterday" are how you tell the AI which kind of record to look for. Without those keywords, Smart Log defaults to searching individual foods.
You can mention the meal in your sentence and Smart Log will route the items there automatically:
- "for breakfast I had..." → Breakfast
- "snacking on..." → first Snacks slot
- "for my pre-workout..." → matches a custom slot named Pre-workout
- "snack 2 was a banana" → Snack 2 (exact slot match)
Smart Log uses your actual configured meal slot names (visible in the AI prompt), so custom slots like "Snack 1 / 2 / 3", "Brunch", or "Late Night" all work. It also handles renamed defaults — if you renamed "Breakfast" to "Morning Bowl", saying "for breakfast" still routes there via fuzzy matching.
- It does not log body stats (weight, measurements, etc.)
- It does not support multi-day patterns ("yesterday and today" — yesterday only works for the prior calendar day)
- It does not modify or delete existing diary entries — only adds new ones
- It does not know about diary entries older than yesterday
- Audio is recognized on-device. Android uses the system speech recognizer; the PWA uses your browser's Web Speech API. The audio itself never leaves your device.
- The text transcript is sent to your configured AI provider (Claude/OpenAI/Gemini) for parsing. This is the only network call to a third-party service.
- Food matching is local-first. Your saved foods, meals, recipes, and diary are searched on your own server first. Open Food Facts is only queried as a fallback for foods not in your library.
- Nothing is sent to NutriTrace servers. There are no NutriTrace servers — this is self-hosted.
Smart Log uses a tightly-constrained prompt (~150 tokens in, ~50 out) so it's cheap. On GPT-4o mini or Claude Haiku, logging six meals a day for a year costs roughly $0.10 USD. Gemini's free tier covers it entirely.
- Mention the meal and the food in one sentence: "for breakfast I had 2 eggs and toast" → fewer modal corrections.
- Use the words "meal" and "recipe" explicitly when you want one of those records — otherwise the AI will look for individual foods first.
- The first time Smart Log fires on Android, you'll see a permission prompt for the microphone. Grant it.
- If voice recognition picks up the wrong words, just type into the text input on the modal (after the parser opens) — same matching pipeline runs.
NutriTrace runs as a Progressive Web App in any modern browser. Add it to your home screen for an app-like, full-screen experience. Requires your NutriTrace server to be reachable.
A native Android app built on the same Svelte codebase, wrapped in Capacitor. Use it standalone or connect it to a NutriTrace server for sync.
Install — download the signed APK from the Releases page and install it on your device. You may need to enable "Install from unknown sources" in Android settings.
What you get on Android — Health Connect for steps / sleep / heart rate / weight, native barcode scanning, native notifications (water reminders, meal prompts, goal celebrations), and OIDC SSO via deep link.
Not currently available. iOS development requires a Mac, an iPhone, and a paid Apple Developer account. If you'd like to see this happen, see Support.
- Download the
docker-compose.ymlfrom this repo, or copy it directly:
services:
nutritrace:
image: ghcr.io/traceapps/nutritrace:latest
container_name: nutritrace
ports:
- "3000:3001"
volumes:
- ${DATA_DB_PATH}:/data/db
- ${DATA_UPLOADS_PATH}:/data/uploads
environment:
- DB_PATH=/data/db/nutritrace.db
- UPLOADS_PATH=/data/uploads
- JWT_SECRET=${JWT_SECRET}
- SMTP_HOST=${SMTP_HOST:-}
- SMTP_PORT=${SMTP_PORT:-587}
- SMTP_SECURE=${SMTP_SECURE:-false}
- SMTP_USER=${SMTP_USER:-}
- SMTP_PASS=${SMTP_PASS:-}
- SMTP_FROM=${SMTP_FROM:-}
restart: unless-stoppedNo changes to this file are needed — everything is driven by .env. If you want to pin to a specific version, change latest to a release tag.
- Copy
.env.exampleto.envand fill in your paths:
DATA_DB_PATH=/your/host/path/db
DATA_UPLOADS_PATH=/your/host/path/uploads
JWT_SECRET=your-long-random-secret
# Optional — SMTP for password reset emails and user invites
# If omitted, invites fall back to a copyable link instead of email
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_SECURE=false
# SMTP_USER=you@example.com
# SMTP_PASS=your-password
# SMTP_FROM=NutriTrace <noreply@example.com>Generate a JWT secret:
openssl rand -base64 48- Start the container:
docker compose up -d- Open
http://localhost:3000in your browser.
On first launch, a setup wizard walks you through enabling user management and creating your admin account. If you skip user management, the app runs in single-user mode with no login required.
| Variable | Required | Default | Description |
|---|---|---|---|
DATA_DB_PATH |
Yes | — | Host path for the SQLite database directory |
DATA_UPLOADS_PATH |
Yes | — | Host path for uploaded images and backups |
JWT_SECRET |
If using users | — | Secret key for signing auth tokens. Use a long random string. |
TOKEN_ENC_KEY |
No | derived from JWT_SECRET |
At-rest encryption key for OIDC client secrets and wearable OAuth tokens. Set this if you want to rotate JWT_SECRET without invalidating stored secrets. |
RECOVERY_TOKEN |
No | — | Passphrase required to disable user management from the login page (lockout recovery). Without this the recovery endpoint is disabled. |
LOG_LEVEL |
No | info |
Log verbosity: error | warn | info | debug. Use debug for detailed wellness sync output (Fitbit, Withings, Garmin, Health Connect). |
SMTP_HOST |
No | — | SMTP server hostname (for password reset & invites) |
SMTP_PORT |
No | 587 |
SMTP port |
SMTP_SECURE |
No | false |
true for SSL (port 465), false for STARTTLS |
SMTP_USER |
No | — | SMTP username |
SMTP_PASS |
No | — | SMTP password |
SMTP_FROM |
No | — | From address, e.g. NutriTrace <noreply@example.com> |
AI_PROVIDER |
No | — | Lock Trace to a specific provider for all users: claude | openai | gemini |
AI_API_KEY |
No | — | Shared AI API key. Key is server-side only — never sent to the browser. |
AI_MODEL |
No | provider default | Override the AI model (e.g. claude-haiku-4-5-20251001) |
AI_ENABLED |
No | — | Set to true to auto-enable Trace for all users |
SMTP and AI settings can also be configured in the Settings UI. Environment variables take priority over UI values and lock those fields for all users.
Two host directories must be bind-mounted:
- Database (
DATA_DB_PATH) — SQLite file. Survives container restarts and redeployments. - Uploads (
DATA_UPLOADS_PATH) — Food/meal photos and server-side backups (stored inuploads/backups/). Survives container restarts and redeployments.
Nothing else needs to persist — the container is stateless beyond these two volumes.
docker compose pull
docker compose up -dThe database schema migrates automatically on startup.
| Layer | Technology |
|---|---|
| Frontend | Svelte 4, svelte-spa-router, Vite, PWA (service worker) |
| Backend | Node.js, Express, better-sqlite3 |
| Auth | JWT (httpOnly cookie), bcryptjs |
| Container | Docker, multi-stage Dockerfile |
| CI/CD | GitHub Actions → GitHub Container Registry |
NutriTrace can sync data from Fitbit, Withings, Garmin, and Android Health Connect. Each cloud provider (Fitbit/Withings/Garmin) requires registering a free OAuth application with the respective service and entering the credentials in Settings → Wellness. Health Connect is on-device and needs no developer setup.
- Go to dev.fitbit.com → Register an App
- Application type: Personal
- OAuth 2.0 Application Type: Personal
- Callback URL:
https://your-nutritrace-domain.com/api/wellness/fitbit/callback - Copy the Client ID and Client Secret into Settings → Wellness → Fitbit
- Go to developer.withings.com → create a developer account → New Application
- Callback URL:
https://your-nutritrace-domain.com/api/wellness/withings/callback - Copy Client ID and Client Secret into Settings → Wellness → Withings
Garmin Health API requires a partnership approval (not a free developer program). If you have access, set the callback URL to https://your-nutritrace-domain.com/api/wellness/garmin/callback.
Reads steps, sleep, heart rate, weight, and exercise directly from the Android Health Connect API. Works in the NutriTrace Android app without any server setup — useful for users running fully local/offline. Enable in Settings → Wellness → Health Connect on the Android app and grant the requested permissions.
Note: The callback URLs for Fitbit/Withings/Garmin must use your public domain (not
localhost). All three require HTTPS.
All external API calls are proxied server-side — no keys are exposed to the browser.
- Open Food Facts — free barcode/food search (no key required)
- USDA FoodData Central — US food database (free API key required)
- Mealie — self-hosted recipe manager integration
Optional. Connect any OpenID Connect 1.0 compliant identity provider — Authentik, Keycloak, Authelia, Pocket ID, Auth0, Google, etc. — to sign in to NutriTrace with credentials your IdP already manages. Existing password login keeps working alongside SSO; admins can also disable password login entirely once SSO is set up.
Prerequisite: User Management must be enabled and you must be signed in as an admin. If your instance is single-user, run Settings → User Management → Set Up first to create your admin account (skip this step if you already enabled User Management).
Two ways to configure:
-
UI (admin-only): Settings → Authentication → OIDC providers. Has a card picker for common IdPs that pre-fills sensible defaults (issuer-URL pattern, scope, claim names, branded logo). Custom / Generic OIDC is the fallback for anything not on the list. Enter your provider's
issuer URL,client ID, andclient secret, save, then test discovery with the network-check button before letting users sign in. -
Environment variables (for IaC / docker-compose / k8s deployments): define providers in your
.envand the server bootstraps them on startup. Mirrors how SMTP and AI provider creds are env-locked today.# Single provider — most common case OIDC_ISSUER=https://auth.example.com OIDC_CLIENT_ID=nutritrace OIDC_CLIENT_SECRET=... OIDC_DISPLAY_NAME=Authentik # Optional fields (per-provider) OIDC_SCOPE=openid profile email OIDC_ADMIN_GROUP_CLAIM=groups OIDC_ADMIN_GROUP_VALUE=NutriTraceAdmins OIDC_AUTO_LINK=1 OIDC_AUTO_REGISTER=0 # Multi-provider — use numbered prefix instead OIDC_PROVIDER_2_ISSUER=https://other-idp.example.com OIDC_PROVIDER_2_CLIENT_ID=... OIDC_PROVIDER_2_CLIENT_SECRET=... OIDC_PROVIDER_2_DISPLAY_NAME=Keycloak
OIDC_*(unnumbered) is an alias forOIDC_PROVIDER_1_*. Numbered providers can be added independently of the first. Env-defined providers show with a lock badge in the Settings UI and are read-only — managed entirely from your config files.
Per-provider toggles:
- Auto-link existing users (verified email) — when the IdP says
email_verified=trueand the email matches an existing NutriTrace user, link them silently on first SSO sign-in. Defaults ON; safe for any IdP you trust to verify emails. - Auto-register new users — let anyone with an account at the IdP create a brand-new NutriTrace account on first sign-in. Defaults OFF; leave off for shared IdPs (Google, work SSO) unless you want blanket onboarding.
- Admin group claim / value — optionally elevate users to admin based on a claim. E.g. claim
groupscontaining valueNutriTraceAdmins. Re-evaluated on every sign-in so revoking a user's admin in your IdP propagates immediately.
Mobile: Android in server-connected mode supports SSO too. The app opens the IdP authorize URL in an in-app browser (Chrome Custom Tabs); the IdP redirects back via nutritrace://oidc-callback/ deep link, the app intercepts it and signs you in — no manual paste, no token wrangling.
Security: client secrets are encrypted at rest using the same key derivation as wearable OAuth tokens. Email-based auto-linking only fires when the IdP explicitly flags the email verified, AND the provider's auto-register is enabled — both gates have to be on, since email-based auto-link is the main account-takeover vector if the IdP is dishonest about verification.
NutriTrace ships with English (en) translations covering navigation, settings, login & onboarding, the diary's primary actions, the AI assistant FAB, and most user-visible strings. Pick your active language from Settings → Regional & Units → Language — the change is reactive (no reload needed).
Want to contribute a translation? It's a single JSON file:
- Copy
src/i18n/en.jsontosrc/i18n/<your-locale>.json(e.g.fr.json,de.json,nl.json,pt-BR.json). - Translate the values, leave the keys untouched. HTML/Markdown inside values (e.g.
<strong>,<code>,<br>) stays as-is. npm run i18n:checkreports per-locale coverage — run it locally to see what's missing.- Open a PR. See CONTRIBUTING.md → Translations for conventions, regulatory-term gotchas (nutrient labels — use the term your country's nutrition labels use, not a literal translation), and the existing volunteer thread.
Server-side strings (email subjects, push-notification bodies, AI system prompts) and admin-only settings panels are intentionally English-only for now and will follow once the user-facing scaffolding is stable.
Coming soon:
- Adaptive TDEE — learn your true energy expenditure from intake + weight trend over time
Future:
- iOS app — pending hardware and Apple Developer account access (see Support).
For Android install instructions, see Apps. Recent releases live on the Releases page.
NutriTrace surfaces three derived wellness scores. Where the source device exposes its own value via API, that value is used directly. Where it doesn't, NutriTrace computes one. The computed scores are prefixed Trace in this section to make the distinction explicit.
| Score | Fitbit | Garmin | Withings | Health Connect |
|---|---|---|---|---|
| Sleep | Trace Sleep Score (computed — Fitbit API doesn't expose its own) | Native overallSleepScore |
Native sleep score when present | Trace Sleep Score |
| Daily Readiness | Trace Readiness (computed) | Trace Readiness (computed) | Trace Readiness (computed) | Trace Readiness (computed) |
| Stress | Trace Stress (computed) | Garmin's native stress_avg is stored separately; Trace Stress is also computed |
Trace Stress (computed) | Trace Stress (computed) |
Trace Sleep Score combines sleep duration, deep / REM percentages, SpO₂, HRV, and efficiency into a single 0–100 value (formula in server/routes/fitbit.js). Trace Readiness weighs HRV against a 30-day baseline plus resting HR and last night's sleep, with an activity-spike penalty. Trace Stress is a 7-day-smoothed inverse of HRV + RHR + sleep (formula in server/lib/wellness-scores.js).
These scores prioritize day-to-day consistency across whatever data sources you've connected. They're not intended to match what each device's own app shows — readings may differ from device-native scores.
If a wellness integration on your device behaves wrong (missing data, weird numbers), file an Integration Test report — the more devices reported, the easier it is to spot integration-specific quirks.
Features marked Experimental in Settings (Smart Log, Goal Insights, Food Sharing, Dynamic Calorie Goal, Garmin integration, Nutrition Import, Health Connect on Android) work but haven't been hammered enough to drop the label. Real-world bug reports help promote them to stable. The badge comes off when edge-case handling is solid, not on a calendar.
If you're filing a bug, logs make it 10× faster to fix. Easiest path first:
In-app logs (PWA + Android — recommended):
Settings → Diagnostics → View logs. A 500-line in-memory ring buffer captures console.log/info/warn/error/debug plus uncaught errors. Toggle Verbose to capture extra sync / DB / notification detail. The viewer has Copy / Share / Clear — Share opens the system share sheet (Gmail, Drive, Files) on Android, Web Share API on PWA. No USB cable, no DevTools needed.
Server logs (Docker):
docker logs nutritrace --tail 200For deeper diagnosis, set LOG_LEVEL=debug in your .env and restart. Note: debug logs contain personal health data (HRV, RHR, sleep duration, calorie counts). Redact these before posting publicly.
Browser DevTools (PWA, advanced):
F12 → Console tab. Filter by [wellness], [sync], [diary], etc. depending on the area.
Android via chrome://inspect (advanced fallback): If the in-app log viewer doesn't capture what you need:
- Connect the device to a computer via USB
- Visit
chrome://inspect/#devicesin Chrome - Click "inspect" on the NutriTrace WebView
- Console tab → reproduce the issue → screenshot or copy the output
Where to file: github.com/traceapps/nutritrace/issues. Templates are provided for bug reports, feature requests, and integration test reports.
NutriTrace is free to self-host and always will be. It's built and maintained by one person; donations help cover real costs like an Apple Developer account and Mac/iPhone hardware to enable an iOS port, plus ongoing infrastructure. Donations are appreciated but never required — starring the repo helps with discoverability and costs nothing.
NutriTrace was inspired by two excellent self-hosted nutrition trackers:
- Waistline by David Healey — a privacy-focused Android nutrition diary that proved a great open-source nutrition tracker is possible.
- SparkyFitness by CodeWithCJ — a self-hosted fitness and nutrition tracker that influenced the wellness integrations and goal-tracking approach.
Thanks to both projects for showing what's possible.
AGPL-3.0 — entire codebase including the Android app source.
