Linux fixes: - NodeSource: setup_lts.x does not exist, replaced with setup_22.x - Added sudo apt install nodejs as simplest Ubuntu 26.04 option - nvm version pinned to v0.40.1 (widely verified) - Added auth token note for Gemini SSE config - USERNAME placeholders clarified with whoami hint - systemd service section now covers venv installs Windows fixes: - DILIGENCE_PATH placeholder replaced with auto-resolving PowerShell using double-quoted here-strings and -replace for JSON backslashes - Claude Desktop config now sets both standard and Store paths in one block - Added auth token note for Gemini SSE config - ChatGPT config path caveated (varies by version)
11 KiB
Diligence Fitness — Linux Installation Guide
Complete installation from a clean Linux machine with no dependencies. Tested on Ubuntu 22.04+, Debian 12+. Most steps work on any distro with Python 3.10+ and pip.
1. Install Python and pip
Most Linux distributions include Python 3. Verify:
python3 --version
pip3 --version
If pip is missing:
# Debian/Ubuntu
sudo apt update && sudo apt install python3-pip python3-venv unzip curl
# Fedora
sudo dnf install python3-pip python3 unzip curl
# Arch
sudo pacman -S python-pip python unzip curl
2. Install Node.js
Required for Gemini CLI. Skip if you only plan to use the built-in AI Coach (see Section 7d).
# Debian/Ubuntu — simplest (Ubuntu 26.04 includes Node 22)
sudo apt install -y nodejs npm
# Or via NodeSource for a specific version
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# Fedora
sudo dnf install nodejs
# Arch
sudo pacman -S nodejs npm
# Or via nvm (any distro)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
Verify:
node --version
npm --version
3. Download Diligence
cd ~/Downloads
curl -L -o Diligence.zip https://github.com/DiligenceWorks/Diligence/archive/refs/heads/main.zip
unzip Diligence.zip
cd Diligence-main
Or with git (if installed):
cd ~/Downloads
git clone https://github.com/DiligenceWorks/Diligence.git Diligence-main
cd Diligence-main
4. Install Diligence and dependencies
Option A — System-wide (simpler):
cd ~/Downloads/Diligence-main
pip3 install ".[mcp]" --break-system-packages
The --break-system-packages flag is required on Ubuntu 23.04+ and Debian 12+
due to PEP 668 (externally managed environments). It is safe for user-level
installs.
Option B — Virtual environment (cleaner):
cd ~/Downloads/Diligence-main
python3 -m venv .venv
source .venv/bin/activate
pip install ".[mcp]"
If using a venv, you must activate it (source .venv/bin/activate) each time
before running Diligence.
Note: Unlike Windows, Linux does not need the tzdata pip package. The
system timezone database at /usr/share/zoneinfo/ is used automatically.
5. Start Diligence
cd ~/Downloads/Diligence-main
python3 -m diligence
You should see:
Diligence running at http://localhost:8000
Data: /home/USERNAME/.diligence
MCP: http://localhost:3001/sse
Press Ctrl+C to stop
Open http://localhost:8000 in your browser. Create an account on the
registration page.
To run in the background:
nohup python3 -m diligence > diligence.log 2>&1 &
6. Prepare the MCP stdio launcher
Some AI agents (Claude Desktop) require stdio transport. Create the launcher:
cat > ~/Downloads/Diligence-main/mcp_stdio.py << 'EOF'
from diligence.mcp.server import create_mcp_server
mcp = create_mcp_server(api_url="http://localhost:8000")
mcp.run(transport="stdio")
EOF
Test it (Diligence must be running in another terminal):
cd ~/Downloads/Diligence-main
python3 mcp_stdio.py
If it hangs with no output, that is success (stdio waiting for input). Ctrl+C to stop.
7. Connect an AI Agent
Choose one or more of the following options. All are free.
7a. Gemini CLI (recommended free option)
What: Google's terminal AI agent. 1,000 free requests/day with Google sign-in. Supports stdio and SSE MCP directly — no bridge needed.
Requires: Node.js (Step 2)
Install:
npm install -g @google/gemini-cli
First run — authenticate with Google:
gemini
Follow the browser prompt to sign in with your Google account. One-time setup.
Configure MCP:
Gemini CLI supports SSE directly, so you can point it straight at the running MCP server — no stdio script needed:
mkdir -p ~/.gemini
cat > ~/.gemini/settings.json << 'EOF'
{
"mcpServers": {
"diligence": {
"url": "http://localhost:3001/sse"
}
}
}
EOF
If your Diligence instance has API token auth enabled (check the Agent page at
http://localhost:8000/agent), add headers to the config:
{
"mcpServers": {
"diligence": {
"url": "http://localhost:3001/sse",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_FROM_AGENT_PAGE"
}
}
}
}
Alternatively, use the stdio launcher (no token needed — it connects locally):
{
"mcpServers": {
"diligence": {
"command": "python3",
"args": ["mcp_stdio.py"],
"cwd": "/home/USERNAME/Downloads/Diligence-main"
}
}
}
Replace USERNAME with your actual Linux username (run whoami to check).
Use:
- Start Diligence in one terminal (
python3 -m diligence) - Open a second terminal and run
gemini - Type: "What's my fitness status today?"
Gemini CLI will discover the Diligence MCP tools and use them to answer.
7b. Claude Desktop (free, Debian/Ubuntu only — beta)
What: Anthropic's desktop app. Free with a free Claude account. Official Linux beta released July 9, 2026. Debian/Ubuntu only.
Requires: Ubuntu 22.04+ or Debian 12+, free Claude account
Install:
sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc \
https://downloads.claude.ai/claude-desktop/key.asc
echo "deb [signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] \
https://downloads.claude.ai/claude-desktop/apt/stable stable main" \
| sudo tee /etc/apt/sources.list.d/claude-desktop.list
sudo apt update && sudo apt install claude-desktop
For Fedora, Arch, or other distros, see the community package at github.com/aaddrick/claude-desktop-debian.
Configure MCP:
mkdir -p ~/.config/Claude
cat > ~/.config/Claude/claude_desktop_config.json << 'EOF'
{
"mcpServers": {
"diligence": {
"command": "python3",
"args": ["mcp_stdio.py"],
"cwd": "/home/USERNAME/Downloads/Diligence-main"
}
}
}
EOF
Replace USERNAME with your actual Linux username (run whoami to check).
If using a virtual environment, use the full path to the venv Python:
{
"mcpServers": {
"diligence": {
"command": "/home/USERNAME/Downloads/Diligence-main/.venv/bin/python",
"args": ["mcp_stdio.py"],
"cwd": "/home/USERNAME/Downloads/Diligence-main"
}
}
}
Use:
- Start Diligence in a terminal (
python3 -m diligence) - Quit and reopen Claude Desktop
- Look for a tools/hammer icon indicating MCP is connected
- Type: "What's my fitness status today?"
7c. ChatGPT Desktop (not available on Linux)
OpenAI has not released an official ChatGPT Desktop app for Linux as of August 2026. A sign-up page exists for future availability. Community wrappers (lencx/ChatGPT, Snap packages) do not support MCP.
If you have a ChatGPT paid plan, you can use the Codex CLI instead:
npm install -g @openai/codex
Codex CLI shares MCP configuration and supports stdio servers. Requires a ChatGPT Plus, Pro, or Team plan.
7d. Built-in AI Coach (simplest — no extra apps needed)
What: AI coaching chat built directly into the Diligence web app. No external tools, no config files, no MCP setup. Just needs a free API key.
Free API key providers:
| Provider | Free tier | Get key |
|---|---|---|
| OpenRouter | 26 free models | openrouter.ai/keys |
| Groq | Fast Llama inference | console.groq.com/keys |
| Google AI Studio | Gemini Flash/Pro | aistudio.google.com/apikey |
| Hugging Face | Thousands of models | huggingface.co/settings/tokens |
| Ollama | Run LLMs locally, no key needed | ollama.com |
Setup:
- Sign up at one of the providers above and copy your API key
- In the Diligence browser app, go to Settings > Integrations > AI Coaching
- Paste your API key and select a model
- Use the Coach tab in the bottom navigation
Ollama (fully offline):
If you want AI coaching without any internet dependency:
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1
Then configure Diligence AI Coaching to point at http://localhost:11434.
No API key needed.
Daily Usage
Each time you want to use Diligence:
cd ~/Downloads/Diligence-main
python3 -m diligence
If using a venv:
cd ~/Downloads/Diligence-main
source .venv/bin/activate
python3 -m diligence
Open http://localhost:8000 in your browser. The app runs until you press Ctrl+C.
If using an external AI agent (Gemini CLI, Claude Desktop), make sure Diligence is running first, then open the agent.
Optional: Run as a systemd service
To start Diligence automatically on boot:
sudo tee /etc/systemd/system/diligence.service << EOF
[Unit]
Description=Diligence Fitness
After=network.target
[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME/Downloads/Diligence-main
ExecStart=$(which python3) -m diligence
Restart=on-failure
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now diligence
If using a virtual environment, change ExecStart to:
ExecStart=/home/USERNAME/Downloads/Diligence-main/.venv/bin/python -m diligence
Check status:
sudo systemctl status diligence
journalctl -u diligence -f
Updating
cd ~/Downloads
rm -rf Diligence-main
curl -L -o Diligence.zip https://github.com/DiligenceWorks/Diligence/archive/refs/heads/main.zip
unzip Diligence.zip
cd Diligence-main
pip3 install ".[mcp]" --break-system-packages
Or with git:
cd ~/Downloads/Diligence-main
git pull origin main
pip3 install ".[mcp]" --break-system-packages
Your data is stored in ~/.diligence/ and is preserved across updates.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| "No module named diligence" | Wrong directory or venv not active | cd ~/Downloads/Diligence-main and source .venv/bin/activate if using venv |
| "No module named uvicorn" | Dependencies not installed | pip3 install ".[mcp]" --break-system-packages |
| "No module named mcp.server.fastmcp" | Wrong MCP SDK version | pip3 uninstall mcp -y && pip3 install "fastmcp>=3.0.0" --break-system-packages |
| "externally-managed-environment" | PEP 668 on Ubuntu 23.04+ | Add --break-system-packages or use a venv |
| MCP line shows "not available" | Missing MCP extras | pip3 install ".[mcp]" --break-system-packages |
| Claude Desktop MCP not loading | Wrong config path | Check ~/.config/Claude/claude_desktop_config.json exists |
| Gemini CLI "no tools found" | Settings path wrong | Check ~/.gemini/settings.json has correct cwd path |
| Port 8000 already in use | Another service on that port | python3 -m diligence --port 8080 or stop the conflicting service |