Installation

Installation Methods

Choose the installation method that best suits your needs:

Docker (Recommended)
From Source

Docker deployment is the recommended method for both development and production environments.

Step 1: Install Docker

macOS
Linux
Windows

Download and install Docker Desktop for Mac:

brew install --cask docker

Start Docker Desktop from your Applications folder.

Install Docker Engine and Docker Compose:

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt-get install docker-compose-plugin

Log out and back in for group changes to take effect.

Step 2: Clone Repository

git clone https://github.com/thetahealth/mirobody-health.git
cd mirobody-health

Step 3: Configure Environment

Create your configuration files:

cp .env.example .env
cp config.yaml config.localdb.yaml

Edit .env to set your environment:

ENV=localdb

Add at least one LLM API key to config.localdb.yaml:

# ============ LLM API Keys (At least one required) ============
GOOGLE_API_KEY: ''      # For Gemini models
OPENAI_API_KEY: ''      # For GPT models  
OPENROUTER_API_KEY: ''  # For Claude, DeepSeek, and other models

# ============ Agent Configuration ============
MCP_TOOL_DIRS:
  - mirobody/pub/tools
  - mirobody/pub/tools_health

MCP_RESOURCE_DIRS:
  - mirobody/pub/resources

AGENT_DIRS:
  - mirobody/pub/agents

Step 4: Deploy

./run.sh

The deployment script will build and start all required services.

Build and run from source for development and customization.

Step 1: Clone and Setup

git clone https://github.com/thetahealth/mirobody-health.git
cd mirobody-health

# Create virtual environment
python3.12 -m venv venv
source venv/bin/activate

Step 2: Install System Dependencies

macOS
Linux (Ubuntu/Debian)

xcode-select --install
brew install gcc gfortran fftw hdf5 openblas lapack

sudo apt install -y g++ gfortran build-essential \
  libfftw3-dev libhdf5-dev libblas-dev liblapack-dev

Step 3: Install Python Dependencies

pip install mirobody -r requirements.txt

Step 4: Install Node.js Dependencies

npm install @antv/gpt-vis-ssr ws

Step 5: Setup External Services

Start PostgreSQL and Redis (using Docker for simplicity):

docker-compose up -d postgres redis

Step 6: Configure

cp .env.example .env
cp config.yaml config.localdb.yaml

Edit .env:

ENV=localdb

Add at least one API key and database settings to config.localdb.yaml:

# ============ LLM API Keys (At least one required) ============
GOOGLE_API_KEY: ''
OPENAI_API_KEY: ''
OPENROUTER_API_KEY: ''

# ============ Database Configuration ============
PG_HOST: 'localhost'
PG_PORT: 5432
PG_USER: ''
PG_PASSWORD: ''
PG_DBNAME: ''
PG_SCHEMA: ''

# ============ Redis Configuration ============
REDIS_HOST: 'localhost'
REDIS_PORT: 6379
REDIS_DB: 0
REDIS_PASSWORD: ''

Step 7: Run

python main.py

Server should start on http://localhost:18080. If running under WSL, access from Windows via http://localhost:18080.

Verify Installation

After installation, verify everything is working:

Check service health

curl http://localhost:18080/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.1",
  "services": {
    "database": "connected",
    "redis": "connected"
  }
}

List available providers

curl http://localhost:18080/api/v1/pulse/providers

Should return a list of available health providers.

Check logs

View application logs to ensure no errors:

# Docker deployment
docker-compose logs -f backend

# Direct installation
# Logs will be in the terminal where you ran main.py

Post-Installation Setup

Configure Data Providers

To enable health device integrations, you need OAuth credentials from each provider.See the Configuration guide for detailed instructions on obtaining and setting up OAuth credentials for:

Garmin Connect
Whoop
Custom providers

Set up AI Chat & Agents

To enable AI features, add at least one API key to config.localdb.yaml:

# ============ LLM API Keys (At least one required) ============
GOOGLE_API_KEY: ''      # For Gemini models
OPENAI_API_KEY: ''      # For GPT models
OPENROUTER_API_KEY: ''  # For Claude, DeepSeek, and other models

# ============ Agent Configuration ============
MCP_TOOL_DIRS:
  - mirobody/pub/tools
  - mirobody/pub/tools_health

MCP_RESOURCE_DIRS:
  - mirobody/pub/resources

AGENT_DIRS:
  - mirobody/pub/agents

Mirobody Health includes two agent types:

DeepAgent (LangChain-based): Best for complex tasks, file operations, multi-step planning
BaselineAgent (Native Gemini): Best for simple conversations, lightweight MCP integration

See Tools Overview for configuration details.

Configure Database Encryption

For production, set secure encryption keys:

DATABASE_DECRYPTION_KEY: 'your_32_char_encryption_key'
JWT_KEY: 'your_secure_jwt_secret'

Use strong, randomly generated keys in production. Never commit these to version control.

Set up Cloud Storage (Optional)

Configure S3-compatible storage for data backups:

S3_KEY: 'your_access_key'
S3_TOKEN: 'your_secret_key'
S3_REGION: 'us-east-1'
S3_BUCKET: 'your-bucket-name'

Directory Structure

After installation, your directory structure will look like this:

mirobody-health/
├── mirobody/                  # Main application package
│   ├── chat/                 # Chat and agent services
│   ├── mcp/                  # MCP protocol implementation
│   ├── pulse/                # Health data providers
│   │   ├── theta/           # OAuth providers (Garmin, Whoop, etc.)
│   │   ├── apple/           # Apple Health platform
│   │   ├── core/            # Core health data services
│   │   └── file_parser/     # File processing handlers
│   ├── pub/                  # Public tools and agents
│   │   ├── tools/           # General-purpose MCP tools
│   │   ├── tools_health/    # Health-specific MCP tools
│   │   ├── resources/       # MCP resources
│   │   └── agents/          # Agent implementations
│   ├── server/               # HTTP server
│   ├── user/                 # User authentication
│   └── utils/                # Utilities
├── database/                  # Database schemas and migrations
│   └── resource/             # SQL initialization files
├── image/                     # Logo and branding assets
├── compose.yaml              # Docker Compose configuration
├── config.yaml               # Base configuration (immutable)
├── config.localdb.yaml       # Your environment configuration
├── .env                      # Environment variables
├── main.py                   # Application entry point
├── requirements.txt          # Python dependencies
├── package.json              # Node.js dependencies
├── run.sh                    # Deployment script
└── README.md                 # Documentation

Troubleshooting Installation

Docker installation fails

Problem: Docker commands fail with permission errors.Solution:

# Linux: Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in
newgrp docker

Port conflicts

Problem: Port 18080 is already in use.Solution: Change the port in config.localdb.yaml:

HTTP_PORT: 18081  # Use any available port

Database connection fails

Problem: Cannot connect to PostgreSQL.Solutions:

Verify PostgreSQL is running:
```
docker-compose ps postgres
```

Check connection settings in config.localdb.yaml:

PG_HOST: db  # 'db' for Docker, 'localhost' for local install
PG_PORT: 5432
PG_USER: holistic_user
PG_DBNAME: holistic_db

Check database logs:
```
docker-compose logs postgres
```

Python version mismatch

Problem: Python 3.12 not available.Solutions:

macOS
Linux
Windows

brew install python@3.12

# Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.12

Download from python.org or use pyenv:

pyenv install 3.12
pyenv global 3.12

Module import errors

Problem: ModuleNotFoundError when running the application.Solution:

# Ensure all dependencies are installed
pip install -r requirements.txt

# Install in development mode
pip install -e .

Uninstallation

Docker
Source Installation

Remove all containers, volumes, and images:

# Stop and remove containers
docker-compose down

# Remove volumes (WARNING: This deletes all data)
docker-compose down -v

# Remove images
docker-compose down --rmi all

# Deactivate virtual environment
deactivate

# Remove project directory
cd ..
rm -rf mirobody-health

Next Steps

Configuration

Configure OAuth providers and customize settings

Quick Start

Follow the quick start guide to test your installation

Architecture

Understand how Mirobody Health works

Development

Set up your development environment

Getting Started

Core Concepts

Using Providers

Provider Examples

Tools & MCP

Installation Methods

Step 1: Install Docker

Step 2: Clone Repository

Step 3: Configure Environment

Step 4: Deploy

Step 1: Clone and Setup

Step 2: Install System Dependencies

Step 3: Install Python Dependencies

Step 4: Install Node.js Dependencies

Step 5: Setup External Services

Step 6: Configure

Step 7: Run

Verify Installation

Post-Installation Setup

Directory Structure

Troubleshooting Installation

Uninstallation

Next Steps

Configuration

Quick Start

Architecture

Development

Getting Started

Core Concepts

Using Providers

Provider Examples

Tools & MCP

​Installation Methods

​Step 1: Install Docker

​Step 2: Clone Repository

​Step 3: Configure Environment

​Step 4: Deploy

​Step 1: Clone and Setup

​Step 2: Install System Dependencies

​Step 3: Install Python Dependencies

​Step 4: Install Node.js Dependencies

​Step 5: Setup External Services

​Step 6: Configure

​Step 7: Run

​Verify Installation

​Post-Installation Setup

​Directory Structure

​Troubleshooting Installation

​Uninstallation

​Next Steps

Configuration

Quick Start

Architecture

Development

Installation Methods

Step 1: Install Docker

Step 2: Clone Repository

Step 3: Configure Environment

Step 4: Deploy

Step 1: Clone and Setup

Step 2: Install System Dependencies

Step 3: Install Python Dependencies

Step 4: Install Node.js Dependencies

Step 5: Setup External Services

Step 6: Configure

Step 7: Run

Verify Installation

Post-Installation Setup

Directory Structure

Troubleshooting Installation

Uninstallation

Next Steps