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...
📦 TradAI Setup (Step 2/4): Syncing dependencies...
🔧 TradAI Setup (Step 3/4): Installing pre-commit hooks...
📋 TradAI Setup (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 Environment Doctor
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔧 Checking required tools...
   ✓ Python:  Python 3.11.x
   ✓ UV:      uv 0.5.x
   ✓ Just:    just 1.x

📦 Checking Python packages...
   ✓ tradai-common
   ✓ tradai-data
   ✓ tradai-strategy

🔒 Checking pre-commit...
   ✓ Pre-commit hooks installed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Legend: ✓ OK  ⚠ Warning  ✗ Error (fix required)

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 - MLflow (port 5001) - Experiment tracking

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 (optional for paper trading)
BINANCE_API_KEY=your_api_key
BINANCE_SECRET_KEY=your_secret_key

Note: Service URLs like BACKEND_URL and TRADAI_UI_URL in .env are still used by Docker services for container-to-container communication. 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

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¶