Getting Started with TradAI¶

Complete guide to setting up your TradAI development environment.

Prerequisites¶

Install these tools before proceeding:

Verify Prerequisites¶

uv --version    # Should show 0.5.x or higher
just --version  # Should show 1.x or higher
docker --version

Quick Setup¶

Option 1: Dev Container (Recommended)¶

Open the repository in VS Code and accept "Reopen in Container". All tools are pre-installed.

Option 2: Manual Setup¶

# Clone the repository
git clone https://github.com/tradai-bot/tradai.git
cd tradai

# Run setup (installs Python, syncs deps, configures pre-commit)
just setup

Watch for progress messages:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚀 TradAI Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📍 Step 1/4: Installing Python 3.11...
📦 Step 2/4: Syncing all workspace packages + dev tools...
🔧 Step 3/4: Installing pre-commit hooks...
📋 Step 4/4: Checking environment files...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Setup complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Verify Environment¶

Run the environment doctor to check everything is configured correctly:

just doctor

Expected output:

                         TradAI Doctor
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Check               ┃ Status ┃ Message                         ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Docker              │   ✔    │ Docker version 28.x             │
│ Docker Compose      │   ✔    │ Docker Compose version v2.x     │
│ Python              │   ✔    │ Python 3.11.x                   │
│ UV                  │   ✔    │ uv 0.x.x                        │
│ Just                │   ✔    │ just 1.x.x                      │
│ .env file           │   ✔    │ Found                           │
│ docker-compose.yaml │   ✔    │ Valid                           │
│ pyproject.toml      │   ✔    │ Found                           │
│ backend             │   ✔    │ HTTP 200                        │
│ data-collection     │   ✔    │ HTTP 200                        │
│ strategy-service    │   ✔    │ HTTP 200                        │
│ mlflow              │   ✔    │ HTTP 200                        │
│ Git                 │   ✔    │ Clean                           │
│ Pre-commit hooks    │   ✔    │ Installed                       │
│ Dependencies        │   ✔    │ uv.lock and .venv present       │
└─────────────────────┴────────┴─────────────────────────────────┘

Service checks (backend, data-collection, etc.) show ! if Docker services are not started yet.

Fix any items marked with ✗ before continuing.

Start Services¶

Start all TradAI services with Docker:

# Start services
just up

# Verify services are running
just ps

You should see: - Backend (port 8000) - API gateway - Data Collection (port 8002) - Market data sync - Strategy Service (port 8003) - Backtesting engine

Note: MLflow (port 5001) is optional and not started by default. To include it, use docker compose --profile mlflow up or just up-full (which starts all profiles including MLflow, LocalStack, and Redis).

Verify CLI¶

Test the TradAI CLI:

tradai --help

You should see commands for: - tradai up/down/logs/ps - Docker management - tradai strategy - Strategy management - tradai indicator - Indicator testing - tradai backtest - Backtest visualization - tradai data - Data collection

Environment Configuration¶

CLI Configuration (Recommended)¶

The CLI uses ~/.tradai/config.yaml for service URLs. This is created automatically on first use, or run:

tradai auth config

To target AWS-deployed services instead of localhost, set the environment:

export TRADAI_ENV=dev    # Uses dev URLs from ~/.tradai/config.yaml
tradai doctor services   # Verify connectivity

See CLI Reference > Configuration File for the full config file format.

Service Configuration¶

Copy the example environment file for Docker services:

cp .env.example .env

Key settings in .env:

# Exchange API credentials are configured per-service via JSON format:
# See services/data-collection/.env for DATA_COLLECTION_EXCHANGES

Note: Service URLs like BACKEND_URL and TRADAI_UI_URL in .env are for CLI/host usage. Docker internal URLs are configured in docker-compose.yaml. For CLI usage, prefer ~/.tradai/config.yaml.

Troubleshooting¶

"UV not found"¶

# Reinstall UV
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc  # or restart terminal

"Docker service connection refused"¶

# Restart services
just down
just up

# Check logs for errors
just logs backend

"Pre-commit not installed"¶

uv run pre-commit install

"Cowardly refusing to install hooks with core.hooksPath set"¶

git config --unset-all core.hooksPath
just setup  # Re-run setup

Next Steps¶

1. Create Your First Strategy - Build a custom trading strategy
2. Run Your First Backtest - Test with historical data
3. Explore Indicators - Test indicator expressions

Optional: FreqAI ML Dependencies¶

If working with ML-based strategies (LightGBM, XGBoost, CatBoost):

# Install ML libraries
just setup-freqai

# macOS note: OpenMP will be installed automatically via Homebrew
# Verify ML libs are working
just test-freqai

Running Tests¶

# Unit tests only (fast, no external deps)
just test

# All tests with LocalStack (AWS mocking)
just check
# OR
just check  # Includes lint + typecheck + all tests

# FreqAI ML tests
just test-freqai

# Coverage report
just test-cov

Quick Reference¶