Diligence — Self-Hosted Fitness Rewards with AI Agent Support

Points-based fitness accountability app. Log workouts and food, earn points, unlock rewards. Connect any AI agent via MCP for logging, coaching, and meal planning. Self-hosted, open source, zero cloud dependencies.

Built by DiligenceWorks.

Quick Start

Prerequisites

• Docker Desktop — that's it. No Python, Node.js, or database install needed.
• Docker Desktop runs natively on Windows 10/11, macOS, and Linux.

---

Windows 11 Setup

1. Install Docker Desktop

Download from docker.com/products/docker-desktop.

During installation, the installer presents a checkbox: "Use WSL 2 instead of Hyper-V (recommended)". This is checked by default.

• WSL 2 backend (default): Works on all Windows editions including Home. Lower resource usage, better performance. Requires WSL 2 to be installed first — open PowerShell as Administrator and run wsl --install, then reboot.
• Hyper-V backend: If WSL 2 causes issues (black screen on reboot, kernel errors, or containers won't start), uncheck the WSL 2 box during installation to use Hyper-V instead. Requires Windows Pro, Enterprise, or Education.

Important: Hardware virtualization must be enabled in your BIOS/UEFI settings (Intel VT-x or AMD-V). This is the most common cause of "Docker won't start" issues. Check your laptop/PC manufacturer's documentation for how to access BIOS settings (usually F2, F12, or Del during boot).

2. Clone and run

Open PowerShell:

git clone https://github.com/diligenceworks/diligence
cd diligence
powershell -ExecutionPolicy Bypass -File setup.ps1
docker compose up -d

Or without the script:

git clone https://github.com/diligenceworks/diligence
cd diligence
copy .env.example .env
# Edit .env and set SECRET_KEY to any random string
docker compose up -d

---

macOS Setup

1. Install Docker Desktop

Download from docker.com/products/docker-desktop. Make sure you pick the right installer for your chip:

• Apple Silicon (M1, M2, M3, M4) — download the Apple Silicon .dmg
• Intel — download the Intel .dmg

To check: Apple menu → About This Mac. Look for "Chip" (Apple Silicon) or "Processor" (Intel).

Drag Docker.app to Applications and launch it. Requires macOS 13 Ventura or later.

Alternatively, install via Homebrew: brew install --cask docker

2. Clone and run

Open Terminal:

git clone https://github.com/diligenceworks/diligence
cd diligence
./setup.sh
docker compose up -d

---

Linux Setup

Install Docker Engine and Docker Compose via your distro's package manager, or install Docker Desktop for Linux. Then:

git clone https://github.com/diligenceworks/diligence
cd diligence
./setup.sh
docker compose up -d

---

Open http://localhost and create your account. First user gets admin.

Verify

docker compose ps

You should see 4 containers, all healthy: frontend, backend, mcp-connector, fitness-db.

Features

• Points economy — earn from workouts, food logging, step goals. Daily gate locks rewards until you earn enough. Weekly reset.
• Science-based onboarding — PAR-Q+ safety screening, TTM stages of change, BREQ-2 motivation profiling.
• AI agent integration — 14 MCP tools for logging, coaching, meal planning, and device configuration.
• Meal plans — AI-generated plans with compliance tracking and points integration.
• Activity sync — Strava, Polar (OAuth 2.0). Garmin, Fitbit, Withings, WHOOP, Oura configurable in-app.
• Food search — Open Food Facts (4M+ products) + USDA FoodData Central (400K+ research-grade).
• Program tracking — 90-day structured programs (StrongLifts, Darebee, etc.) with day-by-day progression.
• Configurable rewards — you define what's worth earning. Gaming time, screen time, treats — your rules.

Connecting an AI Agent

Point your agent's MCP config at:

Environment	URL
Local (development)	http://localhost:3001/sse
Behind reverse proxy	https://your-domain/mcp

Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible agent.

Copy the contents of AGENT_GUIDE.md into your agent's system instructions for motivation-aware coaching.

Claude Desktop example

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "diligence": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Then paste the contents of AGENT_GUIDE.md into your Claude Desktop project instructions.

Configuring Integrations

All integrations are configured through the app UI (Settings → Integrations) or through your AI agent. No .env file editing or container restarts needed.

Tell your agent: "I want to connect my Strava" — it will walk you through getting API credentials and store them encrypted.

Data Sovereignty

Diligence is self-hosted software. Your data never leaves your server. No cloud dependency, no vendor lock-in, no telemetry. MIT license — fork it, modify it, keep it forever.

Your fitness data — heart rate, body composition, food intake, GPS traces — is biometric data that deserves sovereignty.

Architecture

┌─────────────────────────────────────────────────┐
│                    nginx                         │
│         (frontend, /api proxy, /mcp proxy)       │
├──────────┬─────────────────┬────────────────────┤
│ React    │   FastAPI        │   MCP Connector    │
│ SPA      │   Backend        │   (14 tools)       │
│          │                  │   port 3001        │
│          ├──────────────────┤                    │
│          │  PostgreSQL 16   │                    │
│          │  (internal only) │                    │
└──────────┴──────────────────┴────────────────────┘

Stack

• Python 3.12, FastAPI, SQLAlchemy (async)
• React 18, Vite
• PostgreSQL 16
• FastMCP (Streamable HTTP/SSE)
• Docker Compose

Updating

git pull
docker compose build
docker compose up -d

Database migrations run automatically on startup. Your data is preserved.

Backing Up

Your data lives in the fitness_db_data Docker volume:

docker compose exec fitness-db pg_dump -U fitness fitness_rewards > backup.sql

To restore:

docker compose exec -i fitness-db psql -U fitness fitness_rewards < backup.sql

Contributing

Contributions welcome. Please open an issue to discuss before submitting a PR.

License

MIT — see LICENSE.