diligence/docs/INSTALL-LINUX.md
Claude 9ab9135ca2 Review and fix documentation errors across all install guides
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)
2026-08-03 08:01:22 +00:00

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.


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:

  1. Start Diligence in one terminal (python3 -m diligence)
  2. Open a second terminal and run gemini
  3. 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:

  1. Start Diligence in a terminal (python3 -m diligence)
  2. Quit and reopen Claude Desktop
  3. Look for a tools/hammer icon indicating MCP is connected
  4. 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:

  1. Sign up at one of the providers above and copy your API key
  2. In the Diligence browser app, go to Settings > Integrations > AI Coaching
  3. Paste your API key and select a model
  4. 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