Configuration reference

Forven reads its configuration from a layered stack: the process environment, a key-value (KV) store inside its SQLite database, an on-disk config.json, and built-in defaults. This page is the operator's reference to that stack — where each layer lives, the order it is consulted in, and the pipeline threshold groups you are most likely to touch. For environment variables, see environment variables. For the friendly UI over nearly all of this, see Settings.

Forven is a research tool. The thresholds described here govern a validation process — they do not create an edge, and no configuration guarantees against loss. Numbers below are illustrative defaults from the current build, not predictions, recommendations, or financial advice.

Where configuration lives

Everything Forven stores lives under one root directory, FORVEN_HOME — ~/.forven by default (on Windows, %USERPROFILE%\.forven). It holds:

• forven.db — the main SQLite database, including the KV settings table. Almost everything you change in the app is stored here.
• forven_lab.db — the lab database.
• config.json — a small file of file-based settings, consulted below the KV store.
• auth.json — encrypted provider and exchange credentials (the key that decrypts them lives elsewhere; see encryption & secrets).
• workspace/ — the operator profile and AI workspace files.
• backups/ — database snapshots (see Updating & backups).

Market data (the Parquet data lake) lives under FORVEN_HOME/data or the repository's data/ folder, depending on how you launch — see FORVEN_DATA_DIR.

If a legacy home from an earlier build exists (~/.juddex or ~/.judex), Forven merges it into ~/.forven on first run and renames the database files (juddex.db → forven.db). You do not migrate by hand.

# Inspect your Forven home on Windows
Get-ChildItem "$env:USERPROFILE\.forven"

Precedence: how a setting is resolved

When Forven needs a value, it consults four layers in order. The first layer that defines the key wins:

1. Environment variable (highest). Process-level overrides such as FORVEN_HOME, FORVEN_PORT, and FORVEN_ALLOW_MAINNET. A safety flag set here cannot be relaxed from inside the app — that ordering is deliberate.
2. KV store. Runtime settings written by the app and the API. The main keys:
   • forven:settings — the general settings blob behind most of the Settings page, including the nested research_settings and data_engine_settings blocks described below.
   • forven:pipeline_thresholds — every promotion-gate threshold on this page.
   • forven:pipeline:settings — pipeline cadence, throughput, and per-stage work-in-progress caps.
   • system_state — the system pause flag and the autonomy mode.
3. config.json on disk. A file-based fallback for a handful of settings (for example the backup AI provider and some regime-gate options).
4. Built-in defaults (lowest). For pipeline thresholds, that is the canonical default configuration shipped with the app — the Default stance.

Config self-heals on load. Each time pipeline thresholds load, they are reconciled against the current defaults: missing keys are filled in, values stored as percentages are converted back to fractions, and structurally unsafe values are repaired with a warning. For example, a stored config that drops walk_forward from the required gauntlet tests has it restored, because without it nothing meaningful gates the path to paper.

How pipeline thresholds resolve

The promotion-gate thresholds are resolved in three steps:

1. Stance preset. pipeline_preset — relaxed, default, strict, or custom — sets every threshold in one move. Choose it in Settings → Lab → Pipeline stance. Editing any single knob flips it to custom, which uses your per-knob values as they are.
2. Your overrides, stored in forven:pipeline_thresholds.
3. Safety floors clamp the result, so no preset, custom value, or automated caller can soften a gate past them. See safety floors.

The side-by-side comparison of the three presets is on the promotion gates page. The tables below give the Default stance.

A few settings sit outside the stance presets, so picking a stance leaves them alone: the quick-screen rule with its widest window and out-of-sample floor, the door into paper (paper_door.*), the paper pool (paper_pool.*), and the live-gate evidence settings (paper_trading.live_*).

The pipeline threshold groups

Drawdowns and returns are stored as fractions (0.30 = 30%), even though the app displays them as percentages.

quick_screen — the triage gate

quick_screen is the cheap first gate, run before a strategy is allowed to spend compute in the gauntlet. quick_screen.rule decides how it judges:

• fair_sample (the default) judges the whole window, in-sample and out-of-sample together. While the window holds fewer than min_trades trades, the quick-screen step doubles it — from the quick-screen backtest window (730 days unless you changed it) up to max_window_days, data permitting, backfilling older history first — so only a strategy below about five trades a year ends up untestable. The out-of-sample slice only has to avoid losing badly.
• strict is the pre-plan screen: a fixed window, with the in-sample and out-of-sample slices judged separately.

Under fair sample, the in-sample/out-of-sample gap, the ratio and a sign flip (negative in-sample, positive out-of-sample) are recorded, not enforced: they appear in the pass message. A strategy that never fires on the 900-bar look-ahead probe is probed again on a 3,600-bar walk before it is reported unverifiable. A tail-risk trap sits outside the config: a win rate above 70% with a profit factor below 1.5 is rejected as a martingale-shaped curve.

gauntlet — the gauntlet→paper gate

gauntlet governs the gauntlet robustness battery and the deliberately achievable gate into paper. Which of these checks block that gate depends on the door into paper.

The five robustness tests are walk_forward, monte_carlo, param_jitter, cost_stress, and regime_split, ordered cheap-first so weak strategies fail fast. The Strict stance adds cost_stress to the required list.

Under the default research door, a FAIL of any of those tests, the walk-forward consistency checks (wfa_min_folds and the fold pass rate) and the robustness score are recorded at the door and enforced at paper → live. The return, drawdown and Monte-Carlo tail-drawdown (mc_max_dd_p95) floors apply under both doors.

The baseline hurdle regresses every walk-forward's out-of-sample returns against buy-and-hold of the same asset and a fixed trend-following rule over the same days and costs. A strategy that only beats zero may just be riding the market. It shows on the strategy page as the Beats baselines row. The estimate is noisy, which is why it only observes at the gauntlet→paper gate by default.

walk_forward — the out-of-sample simulator

robustness_thresholds — the per-test pass marks

The deflated-Sharpe gate is on by default. On an existing install, a one-time startup step switches it on in your stored config; strategies already in paper or live are not re-judged, and if you turn the gate off afterwards it stays off. Under the default research door the DSR is recorded at the door into paper (it ranks the paper queue) and enforced when the strategy applies for live. A sibling only counts as a trial if a completed backtest reached the quick-screen trade floor and it was not judged untestable or look-ahead. An uncomputable DSR is treated as pending evidence, never as grounds for archiving.

paper_door — the door into paper

paper_door decides which gauntlet checks block entry to paper. Paper risks no capital, so by default (mode: research, the Research door) the door stops only strategies that are broken or clearly losing. It still enforces:

• at least min_trades confirmation trades, a non-negative return, an out-of-sample profit factor of at least min_oos_profit_factor and an out-of-sample Sharpe above min_oos_sharpe;
• the drawdown, implausible-metrics and Monte-Carlo tail-drawdown floors;
• no loss under 2× costs (a positive cost-stressed Sharpe).

Every robustness test must still have run with a saved verdict. The selection-bias checks — deflated Sharpe, walk-forward fold rate, regime split, parameter jitter, the Monte Carlo and cost-stress verdicts, and the robustness score — are recorded at the door (shown on the strategy, used to rank the paper queue) and enforced at paper → live. mode: strict (Strict paper) is the pre-plan door: every check blocks paper, the held-back test runs before paper, and a missing source-reconciliation reading blocks. It also switches multi-coin paper strategies off.

paper_pool — how many strategies paper-trade at once

A strategy that passes the door takes a paper slot if one is free. If the pool, its market or its family is full, it waits in a queue (paper_queue_full) in the gauntlet stage, ranked by its recorded evidence — deflated Sharpe, robustness score, out-of-sample Sharpe, and the breadth verdict (general +0.2, mixed +0.05, home_only −0.2). Waiting is capacity, not a rejection, and never counts toward the repeated-failure auto-archive; a queue entry that isn't re-confirmed for 14 days drops. Settings are in Settings → Lab → Paper pool.

The hourly forven-paper-pool-tick job retires first, then admits from the queue, then starts at most one breadth test. A retired strategy is archived with paper_retired:<why> (losing, drawdown, idle or sequential_fail). Live strategies are never retired here.

paper_trading — the strict paper→live gate

The gauntlet→paper gate is deliberately achievable. The paper_trading group is the strict gate that protects real capital. (The public site calls a strategy at this stage a candidate; the stage name is paper.)

paper_trading.live_gate_mode picks the forward-evidence rule (Settings → Lab → Paper to Live gates → Live gate evidence rule):

• sequential (the default) waits for live_min_forward_trades closed paper trades and live_min_paper_days days in paper, then asks three questions. Are the forward results not significantly worse than the backtest? Does the backtest and forward evidence combined — the backtest weighted by live_backtest_weight — clear a bar corrected (Šidák) for how many strategies were in paper over the last live_pool_lookback_days days, at a live_sequential_alpha false-positive rate? Is the forward Sharpe positive? Its state is collecting, continue, go or fail; go never promotes anything by itself. A bigger paper pool raises the bar.
• fixed is the pre-plan rule: the min_paper_days, min_closed_trades, min_paper_sharpe and min_profit_factor_paper floors.

Under the research door, this gate also enforces what the door only recorded (walk-forward fold rate, jitter, regime split, the Monte Carlo and cost-stress verdicts, the robustness score), the deflated Sharpe on backtest plus forward trades, and — last — the one-shot held-back test.

The return, drawdown, profit-factor and ratio keys apply under both rules.

Multi-coin paper strategies. A paper strategy whose breadth test reads general also paper-trades the coins where its unchanged rule made money in that test — home coin first, then best Sharpe, up to multi_coin_max_coins — as one record. Each coin sizes on an equal share of the strategy's paper equity, trades closed on the same UTC day count as one day of evidence, and the coin list is chosen by the breadth test and then frozen. This is paper only: going live with several coins is held (multi_coin_live_review, "Multi-coin live review pending") and the strategy keeps paper trading.

By default live promotion is never automatic: whatever these thresholds say, moving a strategy to live requires you to type GO LIVE and set a per-asset notional ceiling. (The Allow automatic go-live setting, allow_auto_live_promotion, is off by default and needs a typed LIVE to switch on.) The paper→live gate also enforces the baseline hurdle (gauntlet.wfa_baseline_hurdle_live). See promotion gates.

safety_floors — the absolute rails

Safety floors clamp the gates from outside the preset system. They are editable in Settings → Lab → Safety floors; set a floor to 0 (or a ceiling to 1.0) to remove that rail.

The live_* floors guard the real-money gate. Loosen those with care.

live_graduated, dethrone, and testing_mode

"live_graduated": {
  "allocation_schedule": [
    {"week_start": 1, "week_end": 2, "allocation_pct": 25},
    {"week_start": 3, "week_end": 4, "allocation_pct": 50},
    {"week_start": 5, "week_end": 999, "allocation_pct": 100}
  ]
}

Other runtime settings

These keys live in the forven:settings blob, not in forven:pipeline_thresholds. Change them from the app; the paths below are what you see in GET /api/settings.

research_settings — strategy creation and the held-back test

The creation budget, in-flight limit and registration cap are in Settings → System → Throughput (advanced). Automatic search grid is in Settings → Lab → Robustness Gauntlet (Step 2). The held-back test is in Settings → Lab → Research, under Held-back data (research holdout). With the default quarterly roll, the cutoff is the start of the current quarter minus lag_quarters quarters. Each candidate gets one walk-forward on the held-back period: by default when it applies for live, or before paper under Strict paper or with Held-back test runs at set to Gauntlet to paper. established_at is stamped when the holdout is first switched on, and strategies created before it are exempt.

lag_quarters was 2 before the gate-plan update; a one-time startup step changes a stored 2 to 1. Set it back to 2 and it stays.

Risk keys

The hard limits are documented on risk controls. Two keys are new:

data_engine_settings — freshness, collection, storage, research universe

These back the Settings → Data sections (Data Engine, Freshness SLAs, Collection, Storage, Research universe). data_engine_settings.enabled defaults to true; the Data Engine is no longer opt-in.

sla_tiers — how current a stored series must be, by who uses it. Allowed lag is the larger of (missed bars + 1) × the timeframe and the floor. A series is late past its allowed lag and in breach past sla_breach_multiplier (default 3.0) times it.

Other operational settings

• Throughput and cadence — the throughput preset in Settings → System → Throughput writes real values into the loop intervals, worker counts, and the daily strategy-creation budget (Trickle 4, Conserve 12, Balanced 40, Max 120 tasks a day). The scheduler page covers the jobs themselves.
• Backtest windows — the default window and the per-stage windows in Settings → Lab. See backtesting.
• System state — system_state holds the pause flag and the autonomy mode (manual, semi_auto, or auto).
• Notification preferences — forven:notification_preferences holds the per-event Pop-up and Discord switches and the sidebar badge switches from Settings → Notifications. See notifications.
• Retention windows — keys such as retention_activity_log_days (default 90) drive the database pruning job. See maintenance.

Steps: change a pipeline threshold safely

Tune the pipeline from the app rather than editing stored JSON by hand:

1. Open Settings → Lab. Pick a Pipeline stance first; it sets the stance-bound gates at once (not the quick-screen rule, the door into paper, the paper pool or the live-gate evidence settings).
2. To change a single knob, edit it in the Lab section. The stance flips to Custom. Drawdowns and returns are shown as percentages and stored as fractions.
3. Save. The value is written to forven:pipeline_thresholds.
4. On the next load it is normalized and clamped by the safety floors.
5. Promotions evaluated from then on use it. The pipeline board shows which gate each strategy is waiting on.

# Read the resolved pipeline settings over the local API
# (if FORVEN_API_KEY is set, send it in the x-api-key header)
Invoke-RestMethod -Uri "http://127.0.0.1:8003/api/settings/pipeline"

What you'll see

After you save, the Settings form shows the new value and the stance reads Custom. GET /api/settings/pipeline returns the resolved config on the next load. A value looser than a safety floor is clamped to the floor — the gate enforces the floor regardless of what you stored, unless you change the floor itself.

Caveats

• Environment beats everything. FORVEN_ALLOW_MAINNET is read from the environment only and cannot be set from the app. Paper is the default and supported mode; mainnet is default-deny and unsupported.
• Fractions, not percentages. Drawdown and return keys are stored as fractions (0.30 = 30%).
• Safety floors win. A preset or custom value can't go below them; only changing the floor itself can.
• Stale config self-heals. Missing or unsafe keys are repaired on load — don't rely on hand edits to remove a required test; it will be restored.
• The defaults on this page are illustrative values from the current build, not guarantees, and may change between releases.

Related

• Promotion gates — stance presets side by side, and how these thresholds are enforced
• Environment variables — the variables at the top of the precedence stack
• Settings — the app hub that writes most of these values
• The gauntlet — the robustness tests these thresholds judge