> ## 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.

# Quick start

> Get NOVOSKY trading live in under 3 hours. Covers both the guided wizard path and the manual setup path.

## 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](/infrastructure/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)

<Tip>
  For 24/7 live trading you need a machine that stays on. A cheap VPS (\$5–10/month) is the practical answer. See [Deployment](/infrastructure/deployment) for sizing guidance.
</Tip>

***

## Option A — Guided wizard (recommended)

The onboarding wizard handles everything: `.env` setup, model pull, risk questionnaire, and first optimization run.

<Steps>
  <Step title="Clone the repository and install dependencies">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Run the onboarding wizard">
    ```bash theme={null}
    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).
  </Step>

  <Step title="Dry-run to verify connectivity">
    ```bash theme={null}
    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](/configuration) and the [Infrastructure](/infrastructure/deployment) docs.
  </Step>

  <Step title="Go live">
    ```bash theme={null}
    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.
  </Step>
</Steps>

***

## 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`

<Steps>
  <Step title="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)
    ```
  </Step>

  <Step title="Configure .env">
    ```env theme={null}
    API_URL=http://<windows-vm-ip>:6542
    API_TOKEN=your_mt5_api_token
    TELEGRAM_TOKEN=your_bot_token
    TELEGRAM_CHAT_ID=your_chat_id
    ```
  </Step>

  <Step title="Run">
    ```bash theme={null}
    ./novosky_go --dry    # verify connectivity and model load
    ./novosky_go          # live trading
    ```
  </Step>
</Steps>

See [Go binary](/developer/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:

```bash theme={null}
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
```

<Warning>
  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.
</Warning>

***

## .env reference

Create `.env` from the example file:

```bash theme={null}
cp .env.example .env
```

| Variable             | Required | Description                                                                                                           |
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `API_URL`            | Yes      | MT5 REST API base URL, e.g. `http://1.2.3.4:6542`                                                                     |
| `API_TOKEN`          | Yes      | Bearer token for the MT5 API                                                                                          |
| `HF_TOKEN`           | Yes      | Hugging Face Hub access token                                                                                         |
| `HF_REPO_ID`         | Yes      | Your HF model repo, e.g. `yourname/novosky-models`                                                                    |
| `TELEGRAM_BOT_TOKEN` | No       | Telegram bot token for trade alerts                                                                                   |
| `TELEGRAM_CHAT_ID`   | No       | Your Telegram chat or group ID                                                                                        |
| `TELEGRAM_USER_ID`   | No       | Your numeric Telegram user ID (from @userinfobot) — required when using a group chat to restrict commands to you only |
| `SUPABASE_URL`       | No       | Supabase project URL                                                                                                  |
| `SUPABASE_KEY`       | No       | Supabase 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.