Skip to main content

​
Prerequisites

Before setting up your development environment, ensure you have:

Python 3.10+

Required for running the application

Node.js 18+

Required for chart rendering and SSR

Docker & Docker Compose

For running PostgreSQL and Redis

System Build Tools

gcc, gfortran, and scientific libraries

Git

For version control

Code Editor

VS Code, PyCharm, or your preferred IDE

​
Quick Setup

1

Clone the repository

git clone https://github.com/thetahealth/mirobody.git
cd mirobody
2

Install system dependencies

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

Create virtual environment

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install --upgrade pip
4

Install Python dependencies

pip install -e .

# Optional extras
# pip install -e ".[cn]"    # China region (Aliyun OSS, Volcengine, Dashscope)
# pip install -e ".[fin]"   # Financial data (yfinance)
# pip install -e ".[test]"  # Test suite
Mirobody is also published on PyPI as mirobody — pip install mirobody works for a non-editable install.
5

Install Node.js dependencies

npm install --omit=dev
Required for the server-side chart renderer.
6

Start backing services

docker compose up -d pg redis
Or point Mirobody at your own PostgreSQL and Redis.
7

Configure environment

echo "ENV=localdb" > .env
echo "CONFIG_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env
Then edit config.localdb.yaml:
# Required for the default DeepAgent
OPENROUTER_API_KEY: 'sk-or-...'

# Optional alternatives
OPENAI_API_KEY: ''
GOOGLE_API_KEY: ''
ANTHROPIC_API_KEY: ''

# Database (defaults match the compose file)
PG_HOST: 'localhost'
PG_PORT: 5432
PG_USER: 'mirobody'
PG_PASSWORD: ''
PG_DBNAME: 'mirobody'

# Redis
REDIS_HOST: 'localhost'
REDIS_PORT: 6379
REDIS_DB: 0
REDIS_PASSWORD: ''
8

Run the application

python -m main
Server starts on http://localhost:18080.
Under WSL, the same URL is reachable from Windows.

​
Development Tools

.vscode/extensions.json
{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-python.black-formatter",
    "charliermarsh.ruff",
    "tamasfe.even-better-toml",
    "redhat.vscode-yaml"
  ]
}

​
Code Formatting

# Install development dependencies
pip install black ruff pytest pytest-asyncio

# Format code
black .

# Lint code
ruff check .

​
Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=connect --cov-report=html

# Run specific test file
pytest tests/test_provider_garmin.py

# Run integration tests
pytest -m integration

​
Project Structure

mirobody/
├── mirobody/                # Main application package
│   ├── chat/               # Chat and agent services
│   │   ├── adapters/      # Protocol adapters (HTTP, WebSocket)
│   │   ├── agent.py       # Agent registry and loading
│   │   ├── service.py     # Chat service routes
│   │   └── unified_chat_service.py  # Core chat logic
│   ├── mcp/                # MCP protocol implementation
│   │   ├── service.py     # JSON-RPC handler
│   │   ├── tool.py        # Tool loading and execution
│   │   └── resource.py    # Resource management
│   ├── pulse/              # Health data platform
│   │   ├── theta/         # OAuth providers (Garmin, Whoop, etc.)
│   │   ├── apple/         # Apple Health platform
│   │   ├── core/          # Core health services
│   │   ├── file_parser/   # File processing handlers
│   │   └── router/        # API routes
│   ├── pub/                # Public tools and agents
│   │   ├── tools/         # General MCP tools
│   │   ├── tools_health/  # Health-specific MCP tools
│   │   ├── resources/     # MCP resources
│   │   └── agents/        # Agent implementations
│   ├── server/             # HTTP server
│   ├── user/               # Authentication
│   └── utils/              # Utilities
├── database/               # Database schemas and migrations
│   └── resource/          # SQL initialization files
├── 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

​
Key Directories

Chat service with agent orchestration, message history, and protocol adapters for HTTP (SSE) and WebSocket.
MCP protocol implementation with JSON-RPC 2.0 handler, tool/resource loading, and authentication.
Health data platform with OAuth providers, Apple Health integration, file processing, and data aggregation.
Public tools, resources, and agents that can be discovered via MCP. Add custom tools here.

​
Next Steps

Contributing

Learn how to contribute to the project

Testing

Write tests for your code

Provider Integration

Add a new provider integration

Deployment

Deploy your changes