Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.novosky.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

Before you begin, you need:
  • Python 3.11+ on a Linux machine (Ubuntu 24.04 recommended)
  • MetaTrader 5 REST API running on a VM — see Deployment
  • Hugging Face Hub account with an access token — free at huggingface.co
  • Broker account — RoboForex (cent or standard) recommended; any MT5 broker with a BTC/USD pair works at 1:500 leverage
  • Telegram bot (optional but strongly recommended for trade alerts)
  • Supabase project (optional — for trade log sync and the web dashboard)
For 24/7 live trading you need a machine that stays on. A cheap VPS ($5–10/month) is the practical answer. See Deployment for sizing guidance.
The onboarding wizard handles everything: .env setup, model pull, risk questionnaire, and first optimization run.
1

Clone the repository and install dependencies

git clone <repo> && cd novosky
# LightGBM requires libgomp1 (GNU OpenMP). Not always present on minimal VPS images.
sudo apt-get install -y libgomp1
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
2

Run the onboarding wizard

python scripts/onboarding.py --balance 500
The wizard will:
  1. Ask for your MT5 API URL, API token, HF token, and Telegram credentials
  2. Write your .env file
  3. Pull the latest trained models from Hugging Face Hub
  4. Ask 6 questions to recommend a risk profile (1–5)
  5. Run weekly_optimize.py with your chosen profile (~2.5 h on a 2-core VPS)
Replace 500 with your actual starting account balance in USD (or USC for cent accounts).
3

Dry-run to verify connectivity

python trading.py --dry
Watch the output for a few cycles. You should see:
  • [MT5] Connected — MT5 API reachable
  • [MODEL] Signal: HOLD/BUY/SELL conf=0.xx — models loaded and inferring
  • No ERROR lines
If you see errors, check Configuration and the Infrastructure docs.
4

Go live

python trading.py
The bot runs in a ~60-second loop. Every Sunday at 2 am UTC, weekly_optimize.py runs automatically via cron and sends a Telegram report.

​
Option C — Go binary (commercial distribution)

The compiled Go binary ships as a single executable with all ML models embedded. No Python, no Hugging Face Hub, no models/ directory. What you receive: novosky_go + config.json + .env
1

Place files next to the binary

novosky_go          ← the binary (models embedded inside)
config.json         ← copy from the repo and edit to taste
.env                ← your credentials
libonnxruntime.so   ← ONNX runtime library (provided by distributor)
2

Configure .env

API_URL=http://<windows-vm-ip>:6542
API_TOKEN=your_mt5_api_token
TELEGRAM_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id
3

Run

./novosky_go --dry    # verify connectivity and model load
./novosky_go          # live trading
See Go binary for the full build, license, and distribution reference.

​
Option B — Skip optimization, trade now

If you want to start trading immediately with the current pre-trained models: 
cp .env.example .env
# Edit .env: API_URL, API_TOKEN, HF_TOKEN, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, LSE_API_KEY
python ml/hf_hub.py --pull        # download latest models
python trading.py --dry           # verify connectivity
python trading.py                 # live
Without running weekly_optimize.py first, you will use the default config.json (Profile 4 — Growth). Make sure you are comfortable with up to 55% total drawdown before proceeding. Run python scripts/weekly_optimize.py --profile balanced when you have 2.5 hours to properly tune the bot to your account.

​
.env reference

Create .env from the example file: 
cp .env.example .env
VariableRequiredDescription
API_URLYesMT5 REST API base URL, e.g. http://1.2.3.4:6542
API_TOKENYesBearer token for the MT5 API
HF_TOKENYesHugging Face Hub access token
HF_REPO_IDYesYour HF model repo, e.g. yourname/novosky-models
TELEGRAM_BOT_TOKENNoTelegram bot token for trade alerts
TELEGRAM_CHAT_IDNoYour Telegram chat or group ID
TELEGRAM_USER_IDNoYour numeric Telegram user ID (from @userinfobot) — required when using a group chat to restrict commands to you only
SUPABASE_URLNoSupabase project URL
SUPABASE_KEYNoSupabase service role key

​
What happens after the first optimize

After weekly_optimize.py completes successfully:
  • config.json is updated with the best-found parameters for your risk profile
  • All 4 models are retrained and pushed to your HF Hub repo
  • A Telegram message confirms the new score and key metrics
  • The cron job is installed to repeat every Sunday at 2 am UTC
From then on, the system is self-maintaining. Check your Telegram every Monday morning for the weekly report.