How Forven works

The local stack, the execution kernel, the brain and its agents, the strategy-creation loop, the scanner, and how one strategy travels the pipeline — all on your machine.

Forven is a free, open-source, self-hosted quant research workspace. Everything runs on your own machine: a local web app, a local database, a market-data lake, and a pipeline that builds, tests, kills and promotes trading strategies through a disciplined gauntlet before any real capital could be involved.

This page is the big picture: the pieces that make up Forven, where your data lives, and how one strategy travels from an idea to paper trading. For install steps, start with Install; for the stage-by-stage detail, read the pipeline.

Forven is a research tool. Nothing here is financial advice, and any numbers shown in the app or this documentation are illustrative — they are not predictions of profit or loss. Paper trading is the supported mode; live/mainnet is unsupported and at your own risk.

The local stack

Forven runs as a local web application with a few cooperating parts. There is no Forven cloud doing the work.

Backend (FastAPI, port 8003). The local API behind everything. It also hosts the long-running loops: the scheduler, the agent and brain workers, the health monitor, and the data/risk daemon that streams prices and enforces the hard risk controls.
Web UI (port 5173). The app you operate. Pages refresh in real time over a WebSocket feed (/api/ws/live), falling back to polling if the socket drops.
SQLite (forven.db). The system of record: strategies, ideas, backtest results, trades, agent runs, settings, and the audit trail.
The data lake. Market data — candles plus enrichment streams such as funding and open interest — stored as Parquet files. See managing market data.

Your state lives under one directory, FORVEN_HOME (defaults to ~/.forven): the database, config, encrypted credentials, the agents' workspace, and daily database backups.

# Where your data lives (Windows)
echo $env:USERPROFILE\.forven
# forven.db, forven_lab.db, config.json, auth.json, workspace/, backups/

Provider keys and exchange credentials are encrypted at rest, with the key kept outside FORVEN_HOME. With bring-your-own-key model access, your AI provider keys stay on your machine too.

On Windows you can start everything with the desktop launcher; on any platform, start_all does the same. See Install.

One execution kernel

A single execution kernel turns a strategy's signals into positions — entries, exits, stops, take-profits, sizing, fees, slippage, and funding. The backtest walks the kernel over history; paper and live drive the same kernel in real time. So a strategy is validated on exactly the logic that runs it forward, and a gap between backtest and paper is a difference in the market, not in the code. See execution modes.

No agent can place, size, or close a position. Positions change only through the kernel or your own manual controls, behind the risk gates.

The brain and its agents

The brain is the single coordinator — deterministic routing and policy enforcement, not a chatty agent. It receives every result, decides what happens next, drives stage transitions, and enforces the gates. Two rules matter most:

Hub-and-spoke. Agents never task one another. All output returns to the brain, so every transition has one owner and a recorded reason.
Gates are non-negotiable. A strategy that fails a gate is blocked or archived.

Six optional agents do the research work on the model providers you connect: the Strategy Developer writes ideas and the strategy code that tests them, the Simulation Agent runs backtests and validation, the Risk Manager reviews promotions and watches paper and live strategies, the Quant Researcher turns failures into lessons, and the Full-Stack Engineer diagnoses problems you ask it to look at. The brain keeps short working notes and a decision log; the durable knowledge lives in quant skills. See the brain.

You can also talk to Forven directly: the in-app assistant answers questions and proposes actions for you to confirm, and an external AI client can design and test strategies over MCP.

Ideas and the strategy-creation loop

New strategies start from an idea: a thesis about what the market does, the mechanism behind it, and what would disprove it. The Strategy Developer writes the idea up and builds one or more strategies linked to it, which enter the pipeline at the quick screen.

Ideas come from two places:

You. In The Forge, click + Submit idea and describe the idea or paste a source URL. Submitted ideas run in every system mode and don't count against the daily budget. They need a connected AI provider, because the Strategy Developer does the work.
The agents. In Auto mode, a scheduled job asks the Strategy Developer for new ideas within a daily strategy-creation budget (40 tasks a day on the Balanced throughput preset).

How much runs on its own is set by the system mode: Manual (the fresh-install default) freezes every autonomous job, Semi tests what you submit but writes no ideas of its own, and Auto does both. The testing side of the pipeline doesn't need the agent layer at all.

The scanner

The scanner is the trading floor to the pipeline's laboratory. It evaluates strategies in the paper (and, if you wire it up, live_graduated) stage against live data on every bar and hands their signals to the execution kernel, behind the regime gates and the risk gates. Paper fills are simulated in-app on the live Binance feed; nothing is sent to an exchange.

The pipeline — invents and tests strategies; never trades.
The scanner — runs certified strategies forward; paper is simulated.

How a strategy travels the pipeline

quick_screen → gauntlet → paper → live_graduated

The marketing site uses a simpler vocabulary: public "screen" is quick_screen, "candidate" is paper, and "gauntlet" and "live" mean what they say. Below, the real names.

Stage	What it tests	Gate to advance
`quick_screen`	A fair sample: the whole backtest window, widened until it holds 20 trades. Implausible metrics, a losing record, an out-of-sample slice that loses badly.	Pass the quick-screen floors.
`gauntlet`	The robustness battery: walk-forward and parameter jitter by default, plus cost stress, Monte Carlo, and regime split.	The door into paper: not broken or clearly losing (20+ trades, a non-negative return, out-of-sample profit factor of at least 1 and Sharpe above 0, no loss at 2× costs, drawdown and tail floors). The selection-bias checks are recorded, and a strategy waits in a queue while the paper pool is full.
`paper`	Forward trading on live data with simulated fills.	The strict paper→live gate: 20+ forward trades and 30 days, forward trades that confirm the backtest, the breadth test, a Deflated Sharpe of at least `0.90`, the robustness checks recorded at the door, alpha over buy-and-hold and a trend rule, and a pass on the one-shot held-back test.
`live_graduated`	Real orders, under the hard risk controls. Unsupported.	A typed GO LIVE and a required per-asset notional ceiling.

Anything that fails, or can't be fairly tested, goes to the graveyard (archived, rejected or backtest_failed). You can recover a strategy from there.

A few things are worth stressing:

quick_screen is triage. It rejects suspiciously perfect numbers (a Sharpe or profit factor that is too high) because those usually signal a future-bar leak, not an edge.
The gauntlet measures; the gates decide. Every robustness test runs before paper. Paper risks no capital, so the door into paper only stops strategies that are broken or clearly losing, and records the rest; the paper→live gate enforces them. Passing means the edge held up out-of-sample and under stress — not that it will hold up tomorrow.
The newest data is held back. All research stops at a cutoff one quarter back, so the most recent 3–6 months are never seen by research. Each new strategy gets one walk-forward on the held-back months, as the last check before live, and a fail there is final for those parameters. See promotion gates.
Paper is mandatory. You cannot skip it, however good the backtest.
Paper is a managed pool. At most 40 strategies paper-trade at once by default; the rest wait in a queue ranked by their evidence, and paper strategies that are clearly losing are retired automatically.
Evidence goes stale. When the engine or the data changes, earlier verdicts are marked stale and re-validated rather than trusted.
Paper is automatic; live is yours. A strategy that passes the door into paper moves to paper on its own by default (you can switch to approving each one in Approvals). Live always needs your typed confirmation, unless you turn on Allow automatic go-live, which is off by default.

The pipeline page shows every strategy's stage and exactly why it is there.

Local-first, auditable, BYOK

Local-first. Your strategies, data, trades, and history live on your machine.
Auditable. Every stage transition is logged with its reason, every backtest records the engine version and data fingerprint it ran on, and every agent run keeps its transcript.
BYOK. The AI layer is free and uses your own model-provider keys. Forven never resells model tokens, and it only calls models you have connected and selected.

Steps: trace one strategy end to end

Get data. Open Data and use Set up data with the Starter preset (BTC, ETH and SOL). Binance needs no key. A fresh install starts with an empty data lake. (Walkthrough)

Build it. In the Strategy Creator, write entry and exit rules, click Run Backtest and read the out-of-sample vitals. (Walkthrough)

Send it to The Forge. Click Send to Forge →. The strategy enters the pipeline at quick_screen and appears in The Forge.

Run the gauntlet. A fresh install is in Manual mode, so start it from the strategy's page (Runs → Run the Gauntlet). In Semi or Auto mode the pipeline does it for you. (Walkthrough)

Reach paper. When the door into paper passes, the strategy moves to paper automatically, or waits in the paper queue while the pool is full.

Watch it run. Follow it on Paper Trades. Nothing touches real capital. (Walkthrough)

On a default install, Forven stops at paper.

The pipeline — every stage, and why a strategy is where it is
The gauntlet — the robustness battery
Ideas — where new strategies come from
The brain — the orchestrator and its guardrails
Glossary — every Forven term, defined

Forven is a research tool. Results are not predictive, past behaviour does not guarantee future results, and nothing here is financial advice.

How Forven works

On this page