| name | universal_runner |
| description | Instructions for operating the QuanuX Universal Runner (quanux_runner) for Live Trading and Offline Backtesting. |
Universal Runner Operator Guide
The quanux_runner is the core C++ execution engine for QuanuX. Use this skill to execute strategies, run backtests, or deploy to live markets.
1. Capabilities
- Offline Replay: High-performance replay of Databento
.dbn files (MBO/L3 supported).
- Rithmic Replay: Historical tick replay via RApi+ (Trade info).
- Live Trading: Direct connection to Databento Live API via
libdatabento or Rithmic RApi+.
- Zero-Copy Execution: Loads strategies as shared objects (
.dylib/.so) for maximum speed.
2. Usage
Location
Binary is located at: execution-node/cpp/build/quanux_runner
CLI Arguments
| Argument | Required | Description |
|---|
--strategy <path> | Yes | Path to the compiled strategy shared object (.dylib/.so). |
--file <path> | No* | Path to input .dbn file (Offline Mode). Required for Backtesting. |
--key <key> | No* | Databento API Key. Required for Live Mode. |
--symbol <sym> | No | Symbol to subscribe to (default: ES). |
--dataset <ds> | No | Dataset (default: GLBX.MDP3). |
--ruser <u> | No* | Rithmic Username. Required for Rithmic. |
--rpass <p> | No* | Rithmic Password. Required for Rithmic. |
--rexch <e> | No | Rithmic Exchange (e.g., CME). Required for Rithmic. |
--start <ts> | No | Start Timestamp (Unix Epoch). Required for Replay. |
--end <ts> | No | End Timestamp (Unix Epoch). Required for Replay. |
Examples
A. Run Offline Backtest (Recommended)
Use this to verify strategy logic using historical data. Zstd decompression is handled automatically if the runner was linked correctly.
./execution-node/cpp/build/quanux_runner \
--strategy execution-node/cpp/build/demo_strategy.dylib \
--file data/raw/glbx-mdp3-20260122.mbo.dbn
B. Run Live Mode
Requires DATABENTO_API_KEY (env var or arg).
export DATABENTO_API_KEY=db-xc...
./execution-node/cpp/build/quanux_runner \
--strategy execution-node/cpp/build/demo_strategy.dylib \
--symbol ESH6
C. Run Rithmic Replay
Replay historical trades from Rithmic servers.
./execution-node/cpp/build/quanux_runner \
--strategy execution-node/cpp/build/demo_strategy.dylib \
--ruser "DEMO_USER" \
--rpass "DEMO_PASS" \
--symbol "ES.M24" \
--rexch "CME" \
--start 1715000000 \
--end 1715003600
3. Workflow Checklist
Before running, ensure:
- Strategy Built: The strategy must be compiled freshly.
cmake --build execution-node/cpp/build --target <strategy_name>
- Runner Built: The host binary must be up to date.
cmake --build execution-node/cpp/build --target quanux_runner
- Data Ready: For offline mode, ensure the
.dbn file exists and is readable.
4. Troubleshooting
- Exit Code 139 (Segfault):
- Usually means the strategy is crashing (e.g., indicator out of bounds).
- Fix: Add
std::cout logs to on_market_data in the strategy and rebuild to isolate the crash.
- "Symbol not found":
- The strategy
.dylib is missing symbols or ABI mismatch.
- Fix: Ensure
extern "C" { Strategy* create_strategy() ... } is strictly defined in the strategy source.
- "Invalid argument 'key'":
- API Key is missing or invalid in Live Mode.