Settings

Settings is the single place you configure Forven. It is the unified hub at the /settings route, organised into one sidebar of sections — Home, Data, Lab, Trading, Agents, Models, Notifications, System, Sandbox, and the Danger Zone. Most of what you tune here writes to the same local config the rest of the app reads, so a change made in Settings is the same change you could make by hand in config.json. This page is for operators who want to know what each section controls and how to change it safely.

Forven is a research tool. Settings let you tune how the lab operates and how trades are simulated; they do not predict outcomes, and nothing here is financial advice. Defaults are deliberately conservative — change them with intent.

How Settings works

The hub uses hash-based section navigation. Each section is an anchor on the same page — #home, #data, #lab, #trading, #agents, #models, #notifications, #system, #sandbox, #danger — so you can deep-link straight to a section or move between them without a full page load. A search box spans every section, so if you know a field's name you can jump to it without remembering which section it lives in.

Two behaviours matter before you start editing:

• Field-level dirty tracking. Settings tracks which individual fields you have changed. Until you save, those edits are pending, not applied.
• The unsaved-changes guard. If you try to navigate away with pending edits, Forven pops an in-app prompt asking you to save or discard. This is an application prompt, not a native browser dialog. Crucially, the guard preserves dirty state across sections — moving between #lab and #trading does not lose your unsaved edits, so you can stage changes across several sections and save once.

Because dirty state survives section switches, the safe pattern is: make all the edits you intend, review them, then save. Do not assume a change is live until you have saved it.

The setup wizard

On a fresh install the hub integrates a setup wizard that walks first-run configuration — the same fields, presented as a guided sequence rather than a flat list. If you would rather understand what the wizard touches before it runs, this page is the map; see First run & setup for the launch-time bootstrap (FORVEN_HOME creation, seed data, the beta paper-lock) that happens before you reach Settings at all.

The sections

Home

The landing section of the hub. It is the entry point and search surface; the substantive configuration lives in the sections below.

Data

Controls the market-data layer: your datasets, the remote data engine, and backfill behaviour. This is the configuration counterpart to the Data Manager — the /data page is where you operate on data (download, inspect coverage, run backfills), while the Data section here is where you set the defaults that govern that work, such as which source the engine prefers and how backfill is planned.

Lab

Configures the strategy lab: backtesting defaults and optimization behaviour. These keys map to the lab group in config.json — for example the workspace location and the backtest split — so a change here is a change to how every new backtest and optimization run is set up.

Trading

Configures risk limits and approvals for the trading layer. Two things you will reach for here:

• Risk limits — the hard ceilings (max drawdown, daily-loss limit, portfolio budget, per-trade maximum) that the risk page monitors against. Settings is where you set the limits; /risk is where you watch them.
• Approvals — the policy that decides which actions require operator sign-off. The approval modes (smart / manual / off) for each action type are configured under /settings/approvals; the approval queue at /approval reflects that policy but does not set it.

Approval modes are backend-enforced. The Settings UI shows and edits the policy, but the gate itself is applied server-side — flipping a mode in the UI changes the rule the backend obeys, it does not bypass it.

Agents

Configures the agent layer (a Forged-tier capability): model policies and toolset grants. This is the configuration view that pairs with the /agents hub, where the agent cards live. Note one behaviour that differs from the rest of Settings: in the Agents hub, an agent's model assignment persists immediately on selection — there is no save button for that field, and the dirty-tracking/save flow does not apply to it. Treat model changes there as live the moment you pick them.

Models

Bring-your-own-key (BYOK) configuration: your LLM provider keys and the default model assignments. Keys you enter here are encrypted at rest with Fernet and never leave your machine; the key material that protects them lives in a non-synced location outside FORVEN_HOME. For the full provider routing model — primary plus fallback chains, per-provider auth, and how rate-limits trigger fallback — see Models & providers (BYOK).

Forven never resells model tokens. You bring your own provider key; spend is yours and is bounded by the cost caps you set. See Cost controls for the daily cap.

Notifications

Routes events to channels. Each event type can be sent in-app only or pushed to Discord, with dedupe-by-key and a cooldown so a flapping condition does not spam you. Critical alerts are never suppressed by dedupe. You set per-event delivery preferences here; the routing engine reads them whenever an event fires. See Notifications for the routing policy and channel detail.

A representative save writes your channel preferences to the backend:

PUT /api/settings/notification_preferences
{
  "approval_required_to_discord": true,
  "trade_opened_to_discord": false,
  "system_degraded_to_discord": true
}

System

Advanced system configuration. This is the catch-all for lower-level toggles that do not belong to a single functional area. Day-to-day operational controls — system pause, execution mode, autonomy mode, scheduler status — live on the /ops dashboard rather than here; Settings holds the persistent configuration, /ops holds the live levers.

Sandbox

Configuration for the ephemeral compute environment used to test agent and code work under memory, CPU, and wall-time caps. If the sandbox feature is disabled, its operational page renders an empty state rather than an error — and this section is where its availability is governed.

Danger Zone

The destructive operations, deliberately walled off at the bottom of the hub. This is where factory reset lives. Factory reset is selective and operator-gated: you choose which categories to clear — pipeline data (strategies, trades), agent tasks, the activity log, AI memory, settings — and by default it preserves your credentials. It is not a single "wipe everything" button; read the category labels before confirming. For the full breakdown of what each category removes and how it relates to routine pruning, see Database & maintenance.

Danger Zone actions are irreversible. There is no undo for a factory reset. Take a backup first if there is any data you might want back.

Steps: change a setting safely

1. Open /settings.
2. Click the section in the sidebar, or use the search box to jump to a specific field by name.
3. Edit the field. The hub marks it dirty (pending), but does not apply it yet.
4. If you need to change fields in more than one section, switch sections freely — your unsaved edits are preserved across the hub.
5. Review your pending changes, then Save.
6. If you try to leave with unsaved edits, the in-app guard prompts you to save or discard — do not assume an edit is live until you have saved it.

What you'll see: saved values take effect on the next read by the relevant subsystem. A new Lab default applies to your next backtest; a Notifications preference applies to the next event that fires; a Trading risk limit is enforced from the next position evaluation. The exception is an agent's model assignment in the Agents hub, which is live the moment you select it.

Settings vs config.json vs /ops

It is worth being precise about the three surfaces, because they overlap:

In short: Settings is where you configure, /ops is where you operate, and config.json is where both ultimately land.

Caveats

• Nothing is live until you save. Dirty fields are pending edits; the unsaved-changes guard exists precisely because it is easy to forget this. The one exception is an agent's model assignment in the Agents hub, which persists on selection with no save step.
• Approval policy is backend-enforced. The Trading/Approvals UI edits the rule the server obeys — it does not let you skip the gate.
• Provider keys stay local. BYOK keys are Fernet-encrypted on your machine, and the encryption key lives in a non-synced path; backups taken from FORVEN_HOME alone may not include it.
• Danger Zone is irreversible. Factory reset has no undo. It preserves credentials by default, but everything you tick is gone.
• Beta builds hard-lock paper trading. No setting can unlock live trading in a packaged beta build — the lock is enforced below the configuration layer.

Related

• Configuration reference — the config.json keys, structure, and precedence behind Settings.
• Models & providers (BYOK) — provider keys, fallback chains, and routing.
• Notifications — channels, dedupe, and per-event delivery.
• Database & maintenance — factory-reset categories and retention pruning.