Installation Guide — Intellect FinLab Docs

Intellect FinLab runs as a Docker container on your local machine. It connects to Interactive Brokers Trader Workstation (TWS), which must be open and running on the same machine.

Requirement	Mac	Windows
Operating System	macOS 12 (Monterey) or newer	Windows 10 or 11 (64-bit)
RAM	4 GB minimum · 8 GB recommended	4 GB minimum · 8 GB recommended
Disk space	3 GB free (image + data)	3 GB free (image + data)
Docker Desktop	Required — free download	Required — free download
IBKR TWS	Must be installed and running	Must be installed and running
Internet	Required for initial install only	Required for initial install only
Login credentials	Contact your administrator — you will be given a username and password

Your username and password come from your administrator. Contact them before starting if you haven't received your credentials yet.

How It Works

🐳

Docker Desktop

on your Mac/PC

→

📦

Intellect Container

port 8000

→

🔌

IBKR TWS

7496 / 7497

→

🌐

Your Browser

localhost:8000

⚠️

Complete This Before Installing the App

Without API access enabled in TWS, Intellect FinLab cannot connect to IBKR and will start in offline mode.

1

Open TWS and log in

Log in to the correct account type — Paper or Live — depending on which mode you'll use first.

2

Enable API access

Go to Edit → Global Configuration → API → Settings

✅ Check: Enable ActiveX and Socket Clients

❌ Uncheck: Read-Only API

❌ Uncheck: Allow connections from localhost only — required for Docker

3

Note your port number

The port is shown on the same API Settings screen.

📋

PAPER TRADING

7497

Virtual money · Safe to start

⚡

LIVE TRADING

7496

Real capital · Dry run on first boot

4

Leave TWS running

Keep TWS open the entire time Intellect is running. The system handles TWS's nightly restart (~11:45 PM ET) automatically.

✅

TWS Ready Checklist

✓TWS is open and you are logged in
✓"Enable ActiveX and Socket Clients" is checked
✓"Read-Only API" is unchecked
✓"Allow connections from localhost only" is unchecked (required for Docker)
✓Port noted: 7497 (paper) or 7496 (live)

1

Download Docker Desktop for Mac

Go to docker.com/products/docker-desktop and download.

Apple Silicon (M1/M2/M3/M4): Choose "Mac with Apple chip"
Intel Mac: Choose "Mac with Intel chip"

Not sure? Click Apple menu → About This Mac. If it says "Apple M…" you have Apple Silicon.

2

Install it

Open the .dmg → drag Docker to Applications → double-click Docker to start it.

3

Wait for the whale icon to go steady

The 🐳 whale in your menu bar stops animating when Docker is ready.

4

Verify (optional)

docker --version

Expected: Docker version 26.x.x

ℹ️

Windows Requirement: WSL2

Docker on Windows uses WSL2 (Windows Subsystem for Linux 2). Docker will guide you through enabling it if needed.

1

Download Docker Desktop for Windows

Go to docker.com/products/docker-desktop and download the Windows installer.

2

Run the installer

Double-click the .exe. When asked, choose Use WSL2 instead of Hyper-V. Accept all other defaults.

3

Restart if prompted

Windows may restart to finish WSL2 setup. Docker starts automatically after reboot.

4

Allocate resources (recommended)

Docker Desktop → Settings → Resources:

CPU2 cores minimum

Memory4 GB minimum

5

Wait for the whale icon to go steady

The 🐳 Docker icon in the system tray (bottom-right) stops animating when Docker is ready.

✅

Docker Ready — One-Time Setup Complete

Docker starts automatically on future logins. You never need to install it again.

Open Terminal (press Cmd + Space, type Terminal, press Enter) and paste:

terminal — mac · one command install

curl -sSL https://get.intellectfinlab.com/install.sh | bash

💡

Smart installer — handles everything

First run: installs everything from scratch
Subsequent runs: pulls latest image and restarts — same as ~/.intellect/update.sh
~/intellect-data/ — all your trades, settings, and history (never touched)
~/.intellect/ — helper scripts: update.sh, stop.sh, start.sh, logs.sh

Open PowerShell as Administrator (press Win + X, choose Windows PowerShell (Admin)) and paste:

powershell — windows · one command install

irm https://get.intellectfinlab.com/install.ps1 | iex

💡

Smart installer — handles everything

First run: installs everything from scratch
Subsequent runs: pulls latest image and restarts — same as ~\.intellect\update.ps1
C:\intellect-data\ — all your trades, settings, and history (never touched)
%USERPROFILE%\.intellect\ — helper scripts: update.ps1, stop.ps1, start.ps1, logs.ps1

Mode	Port	What It Means
📋 Paper	`7497`	Virtual money — no real capital at risk. Start here.
⚡ Live	`7496`	Real money. Starts in Dry Run — you must click "Go Live" to place real orders.

1

Open the app

http://localhost:8000

2

Confirm your TWS mode is detected

The login page shows a green dot next to each port it can reach. The correct mode is auto-selected.

3

Enter your credentials and sign in

Use the username and password your administrator gave you.

4

Wait for the Health Monitor to go green

Allow 15–30 seconds for the system to connect to TWS and load market data.

5

Set up your profile & Telegram alerts

Go to Config → My Profile to change your password and add your Telegram Chat ID for personal trade alerts.

📲 How to get your Telegram Chat ID

1

Open Telegram and search for @userinfobot

Send it any message — it instantly replies with your personal chat ID number.

2

Search Telegram for @IntellectAlertBot and send it /start

This allows the bot to send you direct messages. Only needed once.

3

Paste your chat ID into Config → My Profile → Telegram Chat ID and save

From now on every trade alert arrives directly in your personal Telegram.

💡

Session Lasts 12 Hours

You stay logged in for the full trading day. After 12 hours you'll be prompted to sign in again.

After login you land on the Health Monitor. Wait 20–30 seconds, then check:

✓
IBKR Connected — green dot. TWS is connected and responding.
✓
Market Data Fresh — prices showing for ES, SPX, SPY, VIX, /NQ, QQQ.
✓
Scanners Active — a number appears next to Scanners.
!
Market Gate: CLOSED — normal outside 9:30 AM–4:00 PM ET. Opens automatically at market open.
i
Dry Run ACTIVE (Live mode) — real orders are off until you click "Go Live" in the control bar.

⚠️

If IBKR Shows Disconnected

1. Confirm TWS is open and you are logged in
2. TWS → Edit → Global Configuration → API → Settings
3. Check "Enable ActiveX and Socket Clients" · Uncheck "Read-Only API"
4. In Intellect: Config → IB Connection → click "Save & Apply"
5. The system probes TWS every 30 seconds and reconnects automatically

☀️ Morning Checklist

1
Docker Desktop is running — whale icon steady in menu bar / system tray
2
TWS is open — logged in to your paper or live account
3
Intellect is running — auto-starts with Docker. No command needed.
4
Open browser — go to http://localhost:8000
5
Verify Health Monitor — IBKR Connected ✓ · Market Data Fresh ✓

💡

You Don't Need to Stop It

Intellect handles market close automatically. It reconnects after TWS's nightly restart (~11:45 PM ET) on its own. Just leave it running.

If you need to stop manually:

stop

docker stop intellect

To start it again:

start

docker start intellect

🔄 Update available — v1.2.0 This banner appears in the dashboard when a new version is available

Normal Update — Use This Every Time

Pulls the latest image from your administrator. New strategies and scanners they release appear in your system automatically. Bug fixes and performance improvements apply instantly. Your existing strategies, custom scanners, passwords, IB connection, and all trade history are never touched.

terminal — mac

~/.intellect/update.sh

powershell — windows

~\.intellect\update.ps1

What gets updated	What stays yours
✅ Bug fixes and performance improvements	✅ Your password
✅ New strategies released by your admin	✅ Your Telegram chat ID
✅ New scanners released by your admin	✅ Your custom strategies
✅ New features and UI improvements	✅ Your TWS connection settings
	✅ All your trades and trade history

Factory Reset — Only When Something Is Broken

If you've accidentally misconfigured strategies or scanners and want a clean slate, factory reset wipes all strategy and scanner settings and restores the latest defaults from your administrator. Use this when normal update isn't enough.

✅

What is always preserved — even after factory reset

Your password and login
Your Telegram Chat ID and alert settings
Your IB connection settings (port, paper/live)
Your custom strategies you built yourself
All trade history and wealth data

terminal — mac · factory reset

~/.intellect/update.sh --reset

powershell — windows · factory reset

~\.intellect\update.ps1 -Reset

⚠️

Factory Reset Restores Strategy Defaults

Any changes you made to built-in strategy settings (profit targets, enable/disable, cooldowns etc.) will be reset to the administrator's defaults. The script asks you to confirm before proceeding — nothing changes until you type Y.

Action	Mac (Terminal)	Windows (PowerShell)
Install (first time)	`curl -sSL https://get.intellectfinlab.com/install.sh \| bash`	`irm https://get.intellectfinlab.com/install.ps1 \| iex`
Update to latest version	`~/.intellect/update.sh`	`~\.intellect\update.ps1`
Factory reset (restore defaults)	`~/.intellect/update.sh --reset`	`~\.intellect\update.ps1 -Reset`
Stop the app	`~/.intellect/stop.sh`	`~\.intellect\stop.ps1`
Start the app	`~/.intellect/start.sh`	`~\.intellect\start.ps1`
Restart (same version)	`docker restart intellect`	`docker restart intellect`
View live logs	`~/.intellect/logs.sh`	`~\.intellect\logs.ps1`
Check if running	`docker ps \| grep intellect`	`docker ps \| Select-String intellect`
Open app in browser	`open http://localhost:8000`	`start http://localhost:8000`

🔴 Cannot open http://localhost:8000 — "This site can't be reached" ▼

Make sure Docker Desktop is running (whale icon in menu bar / system tray)
Run: docker start intellect
Wait 15 seconds, then try http://localhost:8000 again
Still failing? Run docker ps -a | grep intellect — if it shows "Exited", run docker start intellect

🔴 Health page shows "IBKR Disconnected" ▼

Open TWS and log in to your IBKR account
TWS → Edit → Global Configuration → API → Settings
Check "Enable ActiveX and Socket Clients"
Uncheck "Read-Only API"
Uncheck "Allow connections from localhost only"
Click OK — the system reconnects within 30 seconds automatically

🔴 System shows DEGRADED or strategies not firing after restart ▼

This usually resolves itself in 30–60 seconds as market data loads. If it persists:

Check the Health Monitor — wait for all indicators to show green
If IBKR shows Disconnected, see "Health page shows IBKR Disconnected" above
If still degraded after 2 minutes: docker restart intellect

The system is fully self-healing — it reconnects to IBKR and reloads market data automatically. No manual intervention needed in most cases.

🔴 Login page says "TWS Offline" for both Paper and Live ▼

Open TWS and log in
TWS → Edit → Global Configuration → API → Settings → check "Enable ActiveX and Socket Clients"
Scroll down in the same settings screen and uncheck "Allow connections from localhost only" — this is required for Docker to reach TWS
Click OK, then refresh the login page — dots turn green within 2 seconds

⚠️ Windows users: "Allow connections from localhost only" is the most common cause. Docker runs in a separate network and is not considered "localhost" by TWS.

🔴 Login fails — "Live TWS is not running on port 7496" ▼

Switch to the matching mode on the login page (select Paper if Paper TWS is open)
Or close Paper TWS, open Live TWS, then try again

The login page auto-detects open ports — the chip for the closed TWS will be grayed out.

🔴 Login fails — "Invalid username or password" ▼

Contact your administrator. They can reset your password from Config → User Management.

🔴 "Docker: Cannot connect to the Docker daemon" ▼

Open Docker Desktop from Applications (Mac) or Start Menu (Windows). Wait for the whale icon to stop animating, then try again.

🔴 Port 8000 already in use — "address already in use" ▼

Stop and remove the existing container:

docker stop intellect && docker rm intellect

Then re-run the install command from Section 04 and change -p 8000:8000 to -p 8080:8000. Access the app at http://localhost:8080.

🔴 I updated but still see the old version after "docker restart" ▼

Use the update script — it handles this correctly:

~/.intellect/update.sh

Windows: ~\.intellect\update.ps1

🔴 Market data stale or missing after login ▼

Wait 30–60 seconds after login — subscriptions are still loading. If still missing after 2 minutes:

docker restart intellect

🍎 Mac

~/intellect-data/

🪟 Windows

C:\intellect-data\

Inside your data folder

config/Strategies, scanners, settings

runtime/Trade history and lifecycle data

wealth/Paper and live wealth models

history/Market data (OHLCV bars)

logs/System logs

Key facts

BackupCopy the whole folder anywhere

RestorePaste folder back, restart container

UpdatesNever touch this folder

New machineCopy folder → install Docker → run install command

Back Up Your Data

mac — backup

cp -r ~/intellect-data ~/Desktop/intellect-backup-$(date +%Y%m%d)

windows — backup (powershell)

Copy-Item C:\intellect-data -Destination C:\Users\$env:USERNAME\Desktop\intellect-backup-$(Get-Date -Format 'yyyyMMdd') -Recurse

Restore Your Data

Replace the intellect-data folder with your backup copy, then restart:

terminal / powershell

docker restart intellect

Install Intellect FinLab in Minutes

Normal Update — Use This Every Time

Factory Reset — Only When Something Is Broken

Back Up Your Data

Restore Your Data