Installing Backtest Kit: Four Setup Methods Explained

Backtest Kit offers four ways to get a project running, each suited to a different stage of development. Pick the one that matches your situation: the CLI init for a clean start with minimal files to maintain, Sidekick for full visibility into every piece of wiring, Docker for zero-downtime production deployment, or manual installation when you are integrating into an existing codebase.

Prerequisites

Before installing, make sure your environment meets these requirements:

Node.js 18+ — the engine relies on AsyncLocalStorage from the Node.js async_hooks module, which requires Node 18 or later.
TypeScript 5.0+ — required for the strict generic types used across signal schemas, risk validators, and broker adapters.

Installation Methods

CLI Init
Sidekick
Docker
Manual

The CLI Init method is the fastest way to start a new project. All bootstrap wiring — storage registration, notification setup, candle cache warming, graceful shutdown, and the runner harness — lives inside the @backtest-kit/cli package itself. Your project only contains strategy files.

npx @backtest-kit/cli --init --output backtest-kit-project
cd backtest-kit-project
npm install
npm start

You can override the output directory name with any value:

npx @backtest-kit/cli --init --output my-trading-bot

The generated structure looks like this:

backtest-kit-project/
├── package.json              # pre-configured with all backtest-kit dependencies
├── .gitignore
├── CLAUDE.md                 # AI-agent guide for writing strategies
├── content/
│   └── feb_2026.strategy.ts  # example strategy entry point
├── docs/
│   └── lib/                  # fetched automatically on init
├── math/
│   └── feb_2026.pine         # example PineScript indicator
├── modules/
│   ├── dump.module.ts
│   └── pine.module.ts
└── scripts/
    └── fetch_docs.mjs

After scaffolding, the CLI automatically fetches the latest README files for all bundled libraries into docs/lib/. You can refresh them at any time with npm run sync:lib.Once the project is set up, run a backtest with:

npx @backtest-kit/cli --backtest ./content/feb_2026.strategy.ts --symbol BTCUSDT

The CLI init scaffold is intentionally minimal — it is designed to scale from a solo quant’s first strategy all the way to a monorepo of dozens of strategies without any rewriting. The same npx @backtest-kit/cli command that runs your first backtest is the same one that drives a production desk.

The Sidekick scaffold is the “eject” version of CLI Init. Instead of hiding the infrastructure inside the CLI package, Sidekick generates a project where the exchange adapter, frame definitions, risk rules, strategy logic, and the runner script all live as editable source files in your project directory.

npx -y @backtest-kit/sidekick my-trading-bot
cd my-trading-bot
npm start

Use Sidekick when you need full visibility and control over every part of the setup — for example, when you want to customise the exchange adapter, add non-standard risk rules, or see exactly how the bootstrap sequence wires together.The generated project includes a complete, production-ready strategy out of the box:

Multi-timeframe Pine Script strategy — 4H daily trend filter (RSI + MACD + ADX) combined with 15m entry signals (EMA crossover + volume spike + momentum)
Risk management — SL/TP distance validation, Kelly-optimised partial profit taking (33/33/34%), breakeven trailing stop
Binance integration — OHLCV candles, order book depth, and tick-precise formatting via CCXT
Pre-configured backtest frames — February 2024 (bull run), October–December 2025 (sharp drop and sideways)
AI scaffolding — CLAUDE.md for AI-assisted strategy iteration and a pre-configured Ollama Docker stack

The full project structure generated by Sidekick:

my-trading-bot/
├── src/
│   ├── index.mjs                        # Entry point
│   ├── main/bootstrap.mjs               # Mode dispatcher (backtest / paper / live)
│   ├── config/
│   │   ├── setup.mjs                    # Logger, storage, notifications, UI
│   │   ├── validate.mjs                 # Schema validation
│   │   ├── params.mjs                   # Environment variables
│   │   └── ccxt.mjs                     # Binance exchange singleton
│   ├── logic/
│   │   ├── strategy/main.strategy.mjs   # Multi-TF signal logic
│   │   ├── exchange/binance.exchange.mjs
│   │   ├── frame/*.frame.mjs
│   │   ├── risk/sl_distance.risk.mjs
│   │   └── risk/tp_distance.risk.mjs
│   └── math/
│       ├── timeframe_4h.math.mjs
│       └── timeframe_15m.math.mjs
├── config/source/
│   ├── timeframe_4h.pine                # 4H trend filter Pine Script
│   └── timeframe_15m.pine              # 15m signal generator Pine Script
├── scripts/
│   └── cache/
│       ├── cache_candles.mjs
│       └── validate_candles.mjs
├── CLAUDE.md
├── .env
└── package.json

The Docker method provides automatic restarts and zero-downtime trading. The CLI scaffolds a self-contained Docker workspace with a docker-compose.yaml and a strategy entry point — no manual Docker configuration required.

npx @backtest-kit/cli --docker
cd backtest-kit-docker

To override the output directory name:

npx @backtest-kit/cli --docker --output my-docker-workspace

Launch a live bot by passing the mode and strategy file as environment variables:

MODE=live SYMBOL=TRXUSDT STRATEGY_FILE=./content/feb_2026/feb_2026.strategy.ts docker-compose up -d
docker-compose logs -f

Or pin the mode and flags directly in docker-compose.yaml:

command:
  - --live
  - --symbol
  - TRXUSDT
  - --strategy
  - feb_2026_strategy
  - --exchange
  - ccxt-exchange
  - ./content/feb_2026/feb_2026.strategy.ts
  - --ui

The full set of environment variables the Docker entrypoint supports:

Variable	Required	Default	Description
`MODE`	Yes	—	`backtest` \| `live` \| `paper` \| `walker`
`STRATEGY_FILE`	Yes	—	Path to strategy entry point
`SYMBOL`	No	`BTCUSDT`	Trading pair
`STRATEGY`	No	first registered	Strategy name
`EXCHANGE`	No	first registered	Exchange name
`FRAME`	No	first registered	Frame name (backtest only)
`UI`	No	—	Any non-empty value enables `--ui`
`TELEGRAM`	No	—	Any non-empty value enables `--telegram`
`VERBOSE`	No	—	Any non-empty value enables `--verbose`
`NO_CACHE`	No	—	Any non-empty value enables `--noCache`
`NO_FLUSH`	No	—	Any non-empty value enables `--noFlush`

The CLI also supports running multiple symbols in parallel within a single Docker container. See the --entry flag documentation for poweruser multi-symbol fan-out.

The Manual method installs the core library and its peer dependencies directly into an existing project. Use this when you are integrating Backtest Kit into a project that already has its own infrastructure, or when you want full control over your package.json setup.

npm install backtest-kit ccxt ollama uuid

What each dependency does:

Package	Purpose
`backtest-kit`	Core engine — schemas, signal lifecycle, persistence, broker adapter
`ccxt`	Exchange connectivity — OHLCV candle fetching from 100+ exchanges
`ollama`	Local LLM inference — used in `getSignal` for AI-powered signal generation
`uuid`	Signal ID generation — each signal requires a unique `id` field

After installing, wire up your own runner. The minimal entry point registers three schemas and starts a backtest:

import ccxt from 'ccxt';
import { addExchangeSchema, addFrameSchema, addStrategySchema, Backtest, listenDoneBacktest } from 'backtest-kit';

addExchangeSchema({
  exchangeName: 'binance',
  getCandles: async (symbol, interval, since, limit) => {
    const exchange = new ccxt.binance();
    const ohlcv = await exchange.fetchOHLCV(symbol, interval, since.getTime(), limit);
    return ohlcv.map(([timestamp, open, high, low, close, volume]) => ({
      timestamp, open, high, low, close, volume,
    }));
  },
  formatPrice: (symbol, price) => price.toFixed(2),
  formatQuantity: (symbol, quantity) => quantity.toFixed(8),
});

addFrameSchema({
  frameName: '1d-test',
  interval: '1m',
  startDate: new Date('2025-12-01'),
  endDate: new Date('2025-12-02'),
});

addStrategySchema({
  strategyName: 'my-strategy',
  interval: '15m',
  getSignal: async (symbol) => null,
});

Backtest.background('BTCUSDT', {
  strategyName: 'my-strategy',
  exchangeName: 'binance',
  frameName: '1d-test',
});

listenDoneBacktest(async (event) => {
  await Backtest.dump(event.symbol, event.strategyName);
});

The manual installation does not include automatic candle cache warming, graceful SIGINT handling, Telegram notifications, or the web dashboard. Add @backtest-kit/cli as a dev dependency and use it as the runner — even in manual projects — to get these features without writing infrastructure code yourself.

Supported Entry Point Formats

The CLI automatically detects the format of your strategy file and loads it with the appropriate runtime — no flags or configuration required.

All three file formats are supported out of the box. TypeScript files are executed directly via tsx with no compilation step. ES Modules use native import(). CommonJS modules use require().

Format	Extension	Runtime	Use Case
TypeScript	`.ts`	`tsx` via `tsImport()`	TypeScript strategies with cross-format imports (ESM ↔ CJS)
ES Module	`.mjs`	Native `import()`	Modern JavaScript with top-level `await` and ESM syntax
CommonJS	`.cjs`	Native `require()`	Legacy or dual-package strategies

Get Started

Core Concepts

Guides

Strategy Examples

Installing Backtest Kit: Four Setup Methods Explained

Prerequisites

Installation Methods

Supported Entry Point Formats

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Strategy Examples

Documentation Index

​Prerequisites

​Installation Methods

​Supported Entry Point Formats

Build docs developers (and LLMs) love

Prerequisites

Installation Methods

Supported Entry Point Formats