The Trade Director

The Trade Director is a portfolio-level orchestration system that coordinates the execution of multiple strategies simultaneously. It provides centralised risk management through a configurable filter chain.

Standalone vs Trade Director execution

Understanding this distinction is critical for interpreting backtest results.

Standalone mode (no filter)

algo run --strategy kbt --symbols @ES,@NQ,@GC --initial-capital 100000

Each symbol runs as an independent backtest, but --initial-capital is divided evenly across the expansion tasks:

Each of the 3 symbols starts with $100K / 3 ≈ $33,333
Total simulated capital across the run = $100K
No coordination between symbols during execution
Results are combined only for reporting

To trade each symbol with the full --initial-capital instead, run them as separate invocations or use a multi-run JSON config (one run per symbol).

Trade Director mode (with filter or config)

algo run --strategy kbt --symbols @ES,@NQ,@GC --filter max-positions

All strategies share a single coordinated portfolio:

All symbols share one pool of initial capital ($100K total)
Strategies compete for the same capital
Filters coordinate trades across all strategies

Both modes start with the same total simulated capital, but the allocation model differs:

Aspect	Standalone Parallel	Trade Director
Capital allocation	`initial-capital` divided evenly across symbols	All symbols share single pool of `initial-capital`
Position tracking	Independent per symbol	Coordinated across portfolio
Filter evaluation	None	Sequential, portfolio-aware
Execution mode	Truly parallel goroutines	Sequential (for portfolio-dependent filters)
Total simulated capital	1 x initial capital	1 x initial capital

To split a single fixed pot of capital across multiple runs in custom (non-equal) proportions, use the per-run capital-units field — see Allocating capital across runs.

Engaging the Trade Director

The Trade Director is engaged automatically when you use:

--filter on the command line
--config with a config file containing a filters section

Execution modes

Mode	Description
`auto`	Automatically selects based on filter requirements (default)
`parallel`	Strategies run independently in separate threads (fastest)
`sequential`	Strategies run in coordinated order with shared portfolio state

The execution mode is automatically adjusted based on filter compatibility:

No filters or all filters parallel-compatible: Parallel mode (64 workers)
Any filter requires portfolio state: Sequential mode (automatic fallback)
User specifies --execution-mode sequential: Sequential mode (explicit)

Parallel-compatible filters (allow parallel execution):

nil – passthrough
weekday – day-of-week filtering
volatility – volatility threshold filtering
position-size (in fixed mode only)

Portfolio-dependent filters (require sequential mode):

max-positions – portfolio-wide position limits
asset-class – asset class exposure limits
category – category exposure limits
var – portfolio value at risk limits
risk-budget – percentage-of-equity risk budgets
atr-position-size – ATR-based volatility position sizing
position-size (in risk-parity or equal-weight mode)

Execution mode errors

If you force parallel mode with incompatible filters, an error is raised at startup:

Error: cannot use parallel mode with filters: [max-positions, var]
Hint: remove --execution-mode=parallel or use only parallel-safe filters

If a strategy queries portfolio state while running in parallel mode:

Error: Portfolio query not available in parallel execution mode

Bar coordination

The Trade Director uses a 1-minute time grid in UTC to ensure deterministic execution across strategies with different bar intervals and timezones. For each minute:

Check which strategies have bars completing at this moment
Execute those strategies to generate orders
Process orders through the filter chain
Execute approved orders
Update portfolio state

Filters