Configuration reference

Forven reads its configuration from a layered stack: process environment, a SQLite key-value store, 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 they are consulted, and the key groups you are most likely to touch. For the full list of startup and safety environment variables, see environment variables; for the friendly UI over most of these settings, 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). That directory holds:

• config.json — the on-disk pipeline and lab configuration.
• forven.db and forven_lab.db — the SQLite stores, including the key-value (KV) settings table.
• workspace/ — the operator profile and AI workspace files.
• chromadb/ — the vector memory store.

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

# 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 priority). Process-level overrides such as FORVEN_HOME, FORVEN_PORT, FORVEN_EXECUTION_MODE, and FORVEN_ALLOW_MAINNET. Set these for deployment and safety; they cannot be overridden from the UI.
2. KV store (the SQLite settings table). Runtime settings written by the UI and API live here under keys like forven:settings, forven:pipeline_thresholds (the canonical gate-threshold store), forven:pipeline:settings (cadence and throughput), and system_state. This is where most of what you change in Settings is persisted.
3. config.json on disk. File-based defaults for the pipeline and lab.
4. Built-in defaults (lowest priority). The canonical DEFAULT_PIPELINE_CONFIG baked into the app.

Because the KV store sits above config.json, a value you change in the UI takes precedence over the file. Because environment variables sit above the KV store, a safety flag set in the environment cannot be relaxed from inside the app — that ordering is deliberate.

Config self-heals on load. When the app loads pipeline settings, _normalize_pipeline_config reconciles your stored config against the current defaults: missing keys are filled in, and structurally unsafe values are repaired with a warning logged. For example, a stored config that drops walk_forward from the required gauntlet tests is auto-restored, because dropping it would starve the gauntlet gate.

The config.json key groups

The pipeline configuration is organised into groups. The defaults below are the current build's values — illustrative, and subject to change between releases. Drawdowns and returns are stored as fractions (0.30 = 30%) even though the UI may display them as percentages.

quick_screen — the triage gate

quick_screen is the cheap first gate (the public site calls this stage screen). It runs the S00552 overfitting guardrails before a strategy is allowed to pay for the expensive gauntlet.

A handful of guardrails are hardcoded rather than configurable — for example the tail-risk trap (reject when win rate is above 70% but profit factor is below 1.5) — because they are launch-hardening safety gates, not tuning knobs. (The in-sample Sharpe floor min_is_sharpe is a quick_screen key and defaults to 0.0 — it rejects negative-Sharpe training periods.)

gauntlet — the robustness battery gate

gauntlet governs the gauntlet robustness battery and the lean gauntlet→paper gate.

The five robustness tests are walk_forward, monte_carlo, param_jitter, cost_stress, and regime_split. They are ordered cheap-first (v2 workflow) so weak strategies fail fast.

walk_forward — the out-of-sample simulator

robustness_thresholds — the per-test pass marks

paper_trading — the strict paper→live gate

The gauntlet→paper gate is deliberately lean (achievable in adverse regimes). The paper_trading group is the strict edge-proof gate that protects real capital — the public site calls a strategy in this stage a candidate, but the real stage name is paper.

Capital-gate floors cannot be loosened. Config knobs let you make the paper→live gate stricter but never looser: _PAPER_GATE_FLOORS hardcodes minimums (robustness ≥ 50, Monte-Carlo drawdown ≤ 40%, walk-forward fold pass rate ≥ 40%, param-jitter pass rate ≥ 60%, min trades ≥ 30) so relaxing config cannot bypass the capital gate. The full gate behaviour lives on the promotion gates page.

live_graduated 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}
  ]
}

Runtime settings in the KV store

Not everything lives in config.json. Several operational settings are written to the KV store by the UI and API, and take precedence over the file:

• Pipeline cadence and throughput — forven:pipeline:settings, tuned from /ops and surfaced on the scheduler page (for example throughput_auto_scheduler_control).
• System state — system_state holds the pause flag and the autonomy mode (manual / semi_auto / auto).
• Notification preferences — forven:notification_preferences routes events to in-app or Discord.
• Retention windows — maintenance retention keys (for example retention_activity_log_days) drive the database pruning job.

Steps: change a pipeline threshold safely

Most operators tune the pipeline from the UI rather than editing JSON by hand. To raise a gate threshold:

1. Open Settings (/settings) and find the Lab or Trading section that owns the knob (for example, the gauntlet robustness floor).
2. Change the value. Remember drawdowns and returns are fractions under the hood — the UI shows percentages.
3. Save. Gate thresholds are written to the canonical KV store (forven:pipeline_thresholds), which takes precedence over config.json.
4. The next pipeline load runs _normalize_pipeline_config, which fills any missing keys and rejects structurally unsafe values with a warning.
5. Confirm the new value is reflected in the relevant gate — promotions evaluated after the change use it.

# 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 resolved config returned by /api/settings/pipeline reflects it on the next load. Because capital-gate floors are hardcoded, a value you set looser than a floor (for example a Monte-Carlo mc_max_dd_p95 above the 40% ceiling, or a robustness floor below 50) is silently clamped back to the floor — the gate will still enforce the floor regardless of what you stored.

Caveats

• Environment beats the file. Safety flags such as FORVEN_EXECUTION_MODE and FORVEN_ALLOW_MAINNET are read from the environment and cannot be relaxed from config.json or the UI. 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%). Set them as fractions if you edit config.json directly.
• You can tighten, not loosen, the capital gate. _PAPER_GATE_FLOORS enforces minimums that config relaxation cannot bypass.
• Stale config self-heals. Missing or unsafe keys are repaired on load with a warning — do not rely on hand-editing 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

• Environment variables — the startup, safety, and credential variables that sit at the top of the precedence stack.
• Settings — the UI hub that writes most of these values to the KV store.
• Promotion gates — how the thresholds here are enforced as a strategy advances.
• Scheduler & jobs — the runtime cadence and throughput settings in the KV store.