Skip to main content
This guide covers the full lifecycle of running NOVOSKY as a trader. You do not need to write code, use Claude, or understand the ML internals. Every step is a standard terminal command.
User lane: do not run local retraining or optimization. Use onboarding, select profile 1-5, pull approved model revisions from R2, and run trading.
For config authority and strict drift checks used by automation, see config_sync.py.

​
What hardware do you need?

You have two options. Both work — it depends on your budget and whether you want everything on one machine.
One Linux VPS runs everything: the MT5 REST API (in Docker) and the trading bot.
ComponentMinimumRecommended
CPU2 cores4 cores
RAM4 GB8 GB
Disk20 GB SSD40 GB SSD
OSUbuntu 22.04Ubuntu 22.04
Suitable cloud VPS: Hetzner CX21 (€4/mo), DigitalOcean 4 GB Droplet ($24/mo), Vultr 4 GB, AWS t3.medium, Azure B2s.The live bot (trading.py) uses under 300 MB RAM at runtime.
MT5 requires Windows. On a Linux-only VPS you run the MT5 REST API inside a Wine-based Docker container. See the MT5 server setup guide.

​
One-time setup (~3 hours)

Recommended: run python scripts/onboarding.py as your very first step. It checks your Python environment, validates .env credentials, tests the MT5 API connection, pulls model files from R2, and sets your risk profile — all in one command.
# All-in-one first-time setup (recommended)
python scripts/onboarding.py --balance 500
Or follow the manual steps:
1

Clone and install

git clone <repo> NOVOSKY
cd novosky
python3.11 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
2

Configure secrets

cp .env.example .env
Open .env and fill in:
API_URL=http://<your-vm-ip>:6542      # MT5 REST API address
API_TOKEN=<your-token>

# Cloudflare R2 (for model downloads)
CF_R2_ACCESS_KEY_ID=<key>
CF_R2_SECRET_ACCESS_KEY=<secret>

# Optional but recommended
TELEGRAM_TOKEN=<bot-token>
TELEGRAM_CHAT_ID=<your-chat-id>
3

Pull the trained models

python ml/r2_hub.py --pull
Downloads ~50 MB of model files from Cloudflare R2 into models/. Takes under a minute.
4

Set your risk profile (1-5) without retraining

python scripts/onboarding.py --balance 500 --profile 3
You can set --profile 1 to --profile 5 directly. If you run onboarding without --profile, it can ask a questionnaire and recommend one.Profile map:
ProfileNameRisk/tradeHard halt
1Steady Income0.5-1.0%20%
2Conservative1.0-1.5%30%
3Balanced1.5-2.0%45%
4Growth2.0-3.0%55%
5Aggressive3.0-4.0%65%
If onboarding asks to run optimization now, choose n in trader mode.
5

Pull the approved revision

python ml/r2_hub.py --pull --revision vYYYYMMDD-p3
Use the revision announced by your developer/operator for your selected profile.
6

Test, then go live

# Dry run — connects to MT5 but places no real orders. Safe to Ctrl+C.
python trading.py --dry

# Live trading
python trading.py
7

Keep it running (optional — PM2)

# Start with PM2 — auto-restarts on crash, skips exit code 99 (hard halt)
bash scripts/pm2-start.sh

# Enable auto-start on VM reboot
bash scripts/pm2-start.sh --setup

# Monitor
pm2 status
pm2 logs novosky --lines 50

​
Weekly routine for traders

Your weekly routine is simple: keep bot running, monitor alerts, and pull new approved revisions. 
# Pull latest approved revision from your operator
python ml/r2_hub.py --pull --revision vYYYYMMDD-p3

# Restart bot after pull
python trading.py --dry
python trading.py
The developer/operator handles all weekly retraining and optimization centrally.

​
If the bot stops unexpectedly

​
Hard drawdown halt (Telegram alert + exit code 99)

You receive: 
HARD DRAWDOWN HALT
Total loss: 45.1% >= 45% limit
Equity: $274.50  |  Start: $500.00
Bot stopped to prevent margin call.
Restart manually after reviewing performance.
This means total losses from your starting balance hit the profile limit. The bot stopped itself to protect you from a margin call. Steps to restart: 
# 1. Check your actual account equity
python3 -c "
from dotenv import load_dotenv; import os, urllib.request, json
load_dotenv()
req = urllib.request.Request(
    os.environ['API_URL'] + '/account',
    headers={'Authorization': 'Bearer ' + os.environ['API_TOKEN']}
)
data = json.loads(urllib.request.urlopen(req).read())
print('Equity:', data.get('equity'))
"

# 2. Update starting_balance_usd in config.json to your current equity
#    Open config.json, find "risk_profile" → change "starting_balance_usd"
nano config.json

# 3. Restart
python trading.py --dry
python trading.py

​
Bot crashed (not a halt)

pm2 status          # check if PM2 restarted it
pm2 logs novosky --lines 100   # find the error
Most crashes are network timeouts from the MT5 API. PM2 restarts the bot automatically within seconds.

​
Changing your risk profile

# Re-run onboarding with a new profile (no retrain)
python scripts/onboarding.py --balance 500 --profile 2

# The running bot picks up the new config on its next cycle (within 60s)
Available profiles:
FlagProfileRisk/tradeHard halt
--profile 1 or --profile steadySteady Income0.5-1.0%20%
--profile 2 or --profile conservativeConservative1.0-1.5%30%
--profile 3 or --profile balancedBalanced1.5-2.0%45%
--profile 4 or --profile growthGrowth2.0-3.0%55%
--profile 5 or --profile aggressiveAggressive3.0-4.0%65%

​
When to do what

SituationAction
Bot is running, Telegram shows tradesNothing — all good
Developer announces new approved revisionPull revision + restart bot
Telegram: Hard Drawdown HaltUpdate starting_balance_usd, optionally lower profile, restart
PM2 shows bot crashedpm2 logs novosky --lines 100 to diagnose
You withdrew funds from MT5Update risk_profile.starting_balance_usd in config.json
You deposited more fundsUpdate risk_profile.starting_balance_usd in config.json

​
What you never need to touch

  • ml/ directory — model training code
  • models/*.pkl / *.onnx — model binaries (managed by r2_hub.py)
  • backtest/ — backtesting code
  • ml_config.json features list — managed by developer optimization pipeline
The only files you might edit manually are config.json (risk profile, starting balance) and .env (API credentials).