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, FORVEN_EXECUTION_MODE, 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.
   • 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.

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.

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.

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.

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 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.)

Live promotion is never automatic: whatever these thresholds say, moving a strategy to live requires you to type GO 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

Several operational settings live in the KV store and are set from the app:

• Throughput and cadence — the throughput preset in Settings → System → Throughput writes real values into the loop intervals, worker counts, and daily develop budget. 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 routes events to the in-app inbox or Discord. 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 every gate at once.
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_EXECUTION_MODE and FORVEN_ALLOW_MAINNET are read from the environment and cannot be relaxed 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