Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/theonetrade/backtest-ollama-crontab/llms.txt

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

Getting from a fresh clone to a completed backtest takes four terminal commands. The steps below follow the exact sequence in the README: build the workspace packages, authenticate your Telegram account via QR code, copy the resulting session file into the strategy folder, then launch the backtest engine against the January 2026 signal set. Before you begin, make sure MongoDB and Redis are reachable at their default ports and that you have a valid CC_OLLAMA_TOKEN for the Ollama cloud service (https://ollama.com) with the gpt-oss:120b model available on your account.
The Ollama client in packages/core/src/config/ollama.ts connects to https://ollama.com (the Ollama cloud service) using a bearer token. Set CC_OLLAMA_TOKEN to your Ollama API key in packages/core/.env before running any step. Make sure the gpt-oss:120b model is available on your Ollama account.

​
Steps

1

Build the workspace packages

Run the build script from the repo root. The script (scripts/linux/build.sh) iterates every directory inside packages/, runs npm install and npm run build in each one. Rollup bundles each package to a self-contained build/index.cjs and rolls up a consolidated types.d.ts alongside it.
npm run build:x
After the build completes you should see packages/core/build/index.cjs, packages/core/types.d.ts, packages/main/build/index.cjs, and packages/main/types.d.ts.
The root tsconfig.json maps the @pro/core and @pro/main path aliases directly to these rolled-up types.d.ts files, so strategy files in content/ get full IntelliSense without rebuilding:
{
  "compilerOptions": {
    "paths": {
      "@pro/core": ["./packages/core/types.d.ts"],
      "@pro/main": ["./packages/main/types.d.ts"]
    }
  }
}
2

Authenticate the Telegram MTProto session

The crawler uses GramJS (the telegram npm package) over the MTProto protocol to read messages from a public channel. You need to authenticate once and persist the session string to a file.
cd ./packages/main
npm run auth
A QR code is printed directly in your terminal. Open the Telegram mobile app, navigate to Settings → Devices → Link Desktop Device, and scan the code. If your account has two-factor authentication enabled, the CLI will prompt you for your 2FA password.On success the client prints Connected! and writes the session string to:
packages/main/session.txt
session.txt is equivalent to a logged-in Telegram credential. Never commit this file to version control. The repo’s .gitignore should already exclude it, but double-check before pushing.
3

Copy the session into the strategy folder

The strategy file reads session.txt at runtime from its own directory so it can subscribe to the configured channel without triggering a new authentication flow. Copy the file you just created:
cp packages/main/session.txt content/jan_2026.strategy/session.txt
If you plan to run multiple strategy experiments in separate subdirectories of content/, copy the session file into each one.
4

Run the January 2026 backtest

Return to the repo root and launch the @backtest-kit/cli runner, passing the strategy entry point and telling it to run in backtest mode. The --cache flag pre-fetches all required candles from the exchange before the replay begins — recommended for a first run so the replay doesn’t stall waiting for network calls.
npm start -- --backtest --ui --entry ./content/jan_2026.strategy/jan_2026.strategy.ts --cache
The --ui flag opens the backtest-kit web dashboard in your browser so you can watch trades fill in real time. When the replay finishes you will see the full P&L summary including the Ollama-gated statistics: +68.90% total PnL, 82% winrate, Sharpe +0.512.

​
CLI Flags Reference

All flags are parsed by packages/main/src/helpers/getArgs.ts using Node’s built-in parseArgs. Every flag is a boolean; unknown flags are silently ignored (strict: false).
FlagTypeDescription
--backtestbooleanRun in backtest mode. Requires --entry. Uses Backtest.background from backtest-kit.
--livebooleanRun in live trading mode. Requires --entry. Uses Live.background from backtest-kit.
--paperbooleanRun in paper trading mode. Requires --entry. Executes strategy logic without placing real orders.
--sessionbooleanAuth session only — runs packages/main/src/main/session.ts to generate session.txt. No strategy is loaded.
--entrybooleanRequired for all modes except --session. Signals that a strategy entry point has been passed as a positional argument (e.g. --entry ./content/...).
--cachebooleanPre-cache candles for all symbols in CC_SYMBOL_LIST before the backtest begins. Fetches 1m candles from frameSchema.startDate to frameSchema.endDate.
Flags are read via singleshot from functools-kit, meaning getArgs() is memoized — the argument vector is parsed exactly once per process, no matter how many modules call getArgs().

​
Environment Variables

All configuration lives in a .env file at the repo root (loaded via dotenv-cli before any npm script). The defaults below are embedded directly in packages/main/src/config/params.ts and work out of the box for local development.
VariableDefaultPurpose
CC_MONGO_CONNECTION_STRINGmongodb://localhost:27017/backtest-pro?wtimeoutMS=15000MongoDB connection string for parser-items and screen-items collections
CC_TELEGRAM_API_ID31861455Telegram MTProto API ID
CC_TELEGRAM_API_HASHca60446c67ce250ee4e789c730163449Telegram MTProto API hash
CC_SYMBOL_LISTBTCUSDT,POLUSDT,ZECUSDT,HYPEUSDT,DOGEUSDT,SOLUSDT,PENGUUSDT,TRXUSDT,HBARUSDT,NEARUSDT,FARTCOINUSDT,ETHUSDT,PUMPUSDTComma-separated symbols for candle caching and strategy iteration
CC_OLLAMA_TOKEN“ (empty)Bearer token sent as the Authorization header to the Ollama cloud service at https://ollama.com

​
What Happens Under the Hood

When you run the backtest command, three things happen in sequence:
backtest.ts calls waitForReady(true) from backtest-kit. This blocks until the CLI has loaded the strategy file, resolved the exchange schema and frame schema, and confirmed that all registered services are ready. The true argument indicates that this is a backtest (not live) run, which affects how getMode() and getContext() behave throughout the strategy.
If --cache is set, backtest.ts iterates CC_SYMBOL_LIST and calls cacheCandles for each symbol using the exchange name, frame start/end dates, and interval: "1m". This populates the local candle store so the replay never has to make live HTTP calls during simulation.
For every symbol in CC_SYMBOL_LIST, Backtest.background(symbol, { exchangeName, strategyName, frameName }) is called. Each invocation runs independently, replaying candles and emitting trades as the strategy’s cron handler fires on each 15-minute tick.

Build docs developers (and LLMs) love

Get started for freeTalk to us