Skip to main content
This guide covers detailed installation and configuration for all components of the Drift platform.

​
System requirements

​
Minimum requirements

  • Node.js: 18.0.0 or higher
  • Python: 3.11.0 or higher
  • npm: 10.8.2 or higher (included with Node.js)
  • Memory: 4GB RAM minimum (8GB recommended for large simulations)
  • Storage: 500MB for dependencies and virtual environment

​
Supported platforms

  • macOS 11+ (Big Sur and later)
  • Ubuntu 20.04+ / Debian 11+
  • Windows 10/11 with WSL2 (recommended) or native

​
Installing Node.js components

1

Verify Node.js installation

Check that you have Node.js 18+ installed:
node --version  # Should show v18.0.0 or higher
npm --version   # Should show 10.8.2 or higher
If you need to install or update Node.js:
brew install node@20
2

Clone the repository

git clone https://github.com/aadit2805/drift.git
cd drift
3

Install dependencies

The project uses npm workspaces to manage the monorepo:
npm install
This installs all dependencies for:
  • Root workspace (Turborepo, TypeScript)
  • apps/web (Next.js frontend)
  • apps/api (Express backend)
The package.json specifies "packageManager": "[email protected]" to ensure consistency.
4

Verify installation

Check that all workspaces are properly installed:
npm run lint
This runs ESLint across all packages. You should see no errors (warnings are okay).

​
Installing Python simulation engine

The Python simulation engine is responsible for running Monte Carlo simulations with NumPy and multiprocessing.
1

Verify Python installation

Check your Python version:
python3 --version  # Should show 3.11.0 or higher
If you need to install Python 3.11+:
brew install [email protected]
2

Create virtual environment

Navigate to the simulation directory and create a virtual environment:
cd simulation
python3 -m venv venv
Using a virtual environment isolates Python dependencies and prevents conflicts with system packages.
3

Activate virtual environment

source venv/bin/activate
Your terminal prompt should now show (venv) prefix.
4

Install Python dependencies

Install all required packages from requirements.txt:
pip install -r requirements.txt
This installs:
  • numpy (>=1.24.0) - Vectorized array operations
  • pandas (>=2.0.0) - Data manipulation
  • pydantic (>=2.0.0) - Data validation
  • openai (>=1.0.0) - Goal parsing with GPT
  • python-dotenv (>=1.0.0) - Environment variable loading
NumPy may take several minutes to install as it compiles optimized binaries for your CPU.
5

Verify Python installation

Test that the simulation engine works:
cd ..
python scripts/test-simulation.py
You should see:
============================================================
Monte Carlo Financial Simulation - Test Suite
============================================================

📊 Input Parameters:
  Starting Balance: $12,300
  Monthly Income: $5,000
  ...

🔄 Running Monte Carlo simulation (10,000 scenarios)...
✅ Simulation complete!

​
Environment configuration

1

Create .env file

Copy the example environment file (if available) or create a new one:
touch .env
2

Configure banking API credentials

Choose either Nessie (sandbox) or Plaid (production):Option A: Nessie (Capital One sandbox)
.env
NESSIE_API_KEY=your_nessie_api_key_here
Get a Nessie API key at https://api.nessieisreal.com/Option B: Plaid (production banking)
.env
PLAID_CLIENT_ID=your_plaid_client_id
PLAID_SECRET=your_plaid_secret_sandbox
PLAID_ENV=sandbox  # or 'development' or 'production'
Sign up for Plaid at https://plaid.com/
3

Configure AI services (optional)

For natural language goal parsing:
.env
# OpenAI (primary)
OPENAI_API_KEY=sk-your-openai-key-here

# Google Gemini (alternative)
GEMINI_API_KEY=your-gemini-key-here
For voice narration of results:
.env
ELEVENLABS_API_KEY=your-elevenlabs-key-here
AI services are optional. Without API keys, Drift falls back to template-based goal parsing.
4

Configure ports (optional)

By default, Drift uses:
  • Port 3000 for the web app
  • Port 3001 for the API server
To change these:
.env
PORT=3001          # API server port
NEXT_PUBLIC_API_URL=http://localhost:3001/api

​
Building for production

1

Build all packages

npm run build
This compiles:
  • API: TypeScript to JavaScript in apps/api/dist/
  • Web: Next.js production build in apps/web/.next/
2

Start production servers

npm run start

​
Development workflow

​
Running services independently

During development, you may want to run services separately: 
npm run dev

​
Seeding test data

Populate the Nessie sandbox with test data: 
npm run seed
This runs scripts/seed-nessie.ts to create sample customers, accounts, and transactions.

​
Running Python scripts

Always activate the virtual environment before running Python code: 
cd simulation
source venv/bin/activate  # On Windows: venv\Scripts\activate
python main.py --mode simulate --input-file ../test-data.json

​
Package overview

​
Root workspace

package.json
{
  "name": "drift",
  "version": "0.1.0",
  "packageManager": "[email protected]",
  "workspaces": ["apps/*"],
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "lint": "turbo run lint"
  }
}

​
API server (apps/api)

Key dependencies:
  • express - HTTP server framework
  • cors - Cross-origin resource sharing
  • @google/generative-ai - Gemini API client
  • openai - OpenAI API client
  • plaid - Plaid banking API
  • elevenlabs - Text-to-speech API
  • tsx - TypeScript execution for development

​
Web app (apps/web)

Key dependencies:
  • next - React framework
  • react-plaid-link - Plaid Link component
  • recharts - Data visualization
  • @react-three/fiber - 3D graphics with Three.js
  • tailwindcss - Utility-first CSS
  • lucide-react - Icon library

​
Troubleshooting

​
Node.js issues

Error: Cannot find module Run npm install again to ensure all dependencies are installed. Error: EACCES: permission denied Don’t use sudo with npm. Fix permissions: 
sudo chown -R $USER:$GROUP ~/.npm
sudo chown -R $USER:$GROUP node_modules

​
Python issues

Error: ModuleNotFoundError: No module named 'numpy' Ensure the virtual environment is activated and dependencies are installed: 
cd simulation
source venv/bin/activate
pip install -r requirements.txt
Error: numpy compilation fails Install build tools: 
xcode-select --install

​
Port conflicts

If ports 3000 or 3001 are already in use: 
# Find process using port 3000
lsof -ti:3000 | xargs kill -9

# Or change port
PORT=3002 npm run dev:api

​
API key errors

Error: NESSIE_API_KEY not found Ensure:
  1. .env file exists in project root (not in subdirectories)
  2. API key is valid and not expired
  3. No extra spaces around the = sign
  4. Restart dev servers after adding environment variables

​
Next steps

Run your first simulation

Follow the quickstart guide to test your installation

API reference

Explore available endpoints and parameters

Architecture guide

Understand how components interact

Goal Parsing

Learn about natural language goal parsing

Build docs developers (and LLMs) love

Get started for freeTalk to us