Skip to content

Configuration

Savvas Leousis edited this page Sep 26, 2026 · 2 revisions

Configuration

Settings come from config/default.toml, then environment variables. Secrets come only from the environment (or .env).

flowchart LR
  D[Code defaults] --> T[config/default.toml] --> E[Env vars and .env]
  E --> S[Settings]
Loading

Later wins. Commands load .env from the working directory, so run them from the repo root.

Sections read by Settings

Section Controls Key settings (default)
[lake] Market data file path (data/lake.duckdb)
[lake.bars] Where bars live backend (duckdb or parquet)
[state] Trading records file path (data/state.sqlite)
[registry] Strategy artifacts artifacts_dir (data/artifacts)
[logging] Log level level (INFO)
[production] The tick universe ([]), threshold (0.0), initial_cash (10000), max_price_staleness_days (7), shadow_enabled (true), dividend_withholding_rate (0.0)
[production.risk] Risk caps enabled, max_open_positions, max_weight_per_ticker (1.0), cash_buffer_fraction (0), min_order_notional (0)
[production.risk.max_weight_per_asset_class] Caps per class e.g. crypto = 0.2
[production.health] Health thresholds max_bar_age_days (4), stuck_tick_minutes (60), stuck_ingest_minutes (180), ingest_failure_lookback_hours (24)
[backtest.costs] Trading costs (lab and simulated tick) impact_bps (100), max_impact_bps (500)
[backtest.costs.default] Fallback costs fee_flat (0), half_spread_bps (2), fee_bps (0.5)
[backtest.costs.asset_classes.<class>] Costs per asset class same keys; crypto 5 bps spread and 10 bps fee
[lab] Lab defaults benchmark (auto), embargo_bars (0)
[lab.walk_forward] Walk-forward defaults n_splits (4), test_days, train_days, anchored (false), metric (sharpe), min_positive_share (0.5), min_mean_score (0), min_wfe (0.5), matrix (false)
[lab.parallel] Worker processes max_workers (0 = every core, up to 32), blas_threads (1)
[notify] Alerts backends (["log", "store"]), min_level (warning)
[notify.webhook] Alert webhook timeout_seconds (5)
[sources.eodhd] EODHD client base_url, timeout_seconds (30), max_retries (3)
[sources.yahoo] Yahoo client timeout_seconds (30), max_retries (3), min_request_interval_seconds (0.5)
[sources.defillama] DefiLlama client base_url, timeout_seconds (30), max_retries (3)
[brokers] Broker of the tick kind (simulated or alpaca)
[brokers.alpaca] Alpaca paper (true), allow_live (false), max_retries (3)
[api] REST server host (127.0.0.1), port (8000), ui_origin, open_reads_on_loopback (true), allowed_hosts, max_concurrent_jobs (2), ui_dist, allow_code_strategies (false)
[golive] Go-live limits min_days (63), max_drawdown (0.15), max_drift (0.10), min_trades (20), incubation (true), ...
[mcp] MCP client api_url, timeout_seconds (30), max_wait_seconds (600)

Sections read by their own block

These are read straight from the TOML file by the block that owns them.

Section Read by Notes
[scheduler], [[scheduler.jobs]] python -m stonks.scheduling See Scheduling and Backups.
[connections] python -m stonks.connections enabled_providers (empty), portal_ttl_minutes, sync_workers.

Not wired yet: [backup], [ingest.quality], [ingest.fallback], [production.construction] and [production.risk.rules.*] have settings models in the code, but Settings ignores them today. Backups and data quality run on their defaults, source fallback is off, the tick uses single_winner unless a portfolio row sets its own construction, and the six newer risk rules stay off.

Environment variables

Variable Purpose
EODHD_API_KEY EODHD data key
ALPACA_API_KEY, ALPACA_SECRET_KEY Alpaca keys (rejected if put in TOML)
STONKS_API_TOKEN Bearer token for the API, MCP and scheduler (rejected if put in TOML)
STONKS_NOTIFY_WEBHOOK_URL Alert webhook URL
STONKS_DATA_DIR Moves lake, state and artifacts under one folder
STONKS_LOG_LEVEL Overrides [logging].level
STONKS_API_URL Makes the scheduler run jobs through the API
STONKS_PING_* Dead-man ping URLs named by ping_url_env on scheduler jobs
STONKS_SECRET_KEYS Master keys that encrypt broker credentials (python -m stonks.security keygen)
STONKS_CONNECTIONS_ENABLED_PROVIDERS Overrides [connections].enabled_providers
STONKS_SNAPTRADE_CLIENT_ID, STONKS_SNAPTRADE_CONSUMER_KEY SnapTrade partner credentials
STONKS_VAPID_PUBLIC_KEY, STONKS_VAPID_PRIVATE_KEY, STONKS_VAPID_SUBJECT Web Push keys (python -m stonks.notify vapid-keygen)
STONKS_SMTP_HOST, _PORT, _USERNAME, _PASSWORD, _FROM, _SECURITY Optional email channel
STONKS_NOTIFY_* Notification outbox tuning (retries, backoff, dedupe window)
STONKS_ALLOW_DESTRUCTIVE_MIGRATIONS 1 lets db init run a migration that drops data
STONKS_RUN_LIVE_TESTS 1 enables live network tests

Start from .env.example. .env is gitignored; never commit secrets.

Clone this wiki locally