How Forven works

The local stack, the brain orchestrator, the research daemon, the scanner, and how one strategy travels the pipeline — all on your machine.

Forven is a local-first quant research lab. Everything runs on your own machine: a desktop app, a local database, and a research loop that builds, tests, kills, and promotes trading strategies through a disciplined gauntlet before any real capital is involved.

This page is the big picture. It explains the pieces that make up Forven, where your data lives, and how a single strategy travels from an idea to (at most) live execution. If you want the install steps, start with Install; if you want the full 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. Live trading is gated, and beta builds hard-lock to paper.

The local stack

Forven runs as a desktop application with a small set of cooperating services. There is no Forven cloud doing the work — the heavy lifting happens locally.

Backend (FastAPI). A local HTTP API serves the app and coordinates the system. It runs on your machine and is reached over 127.0.0.1.
Frontend (SvelteKit). The browser-based UI you operate: dashboard, lab, data manager, risk page, and the rest. 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, backtest results, trades, hypotheses, tasks, and settings all persist here.
ChromaDB memory. A local semantic store for backtest results, research artifacts, and the quant-skills knowledge base — searchable context the system draws on for decisions.

All of this lives under one workspace directory, FORVEN_HOME (defaults to ~/.forven). Your database, auth tokens, config, and the memory store sit inside it.

# Where your data lives (Windows)
echo $env:USERPROFILE\.forven
# forven.db, auth.json, config.json, chromadb/ all live here

If you set FORVEN_ENCRYPTION_KEY, portable secrets such as auth tokens and exchange keys are encrypted at rest. Keys and data stay on your machine; bring-your-own-key model access (the Forged tier) keeps your LLM credentials in the local keystore too.

The brain: the sole orchestrator

The brain is the single coordinator. It is not itself a chatty agent — it is deterministic routing logic plus policy enforcement. The brain receives every result from the agents, routes the next decision, drives stage transitions, and enforces the quality gates that strategies must clear to advance.

Two rules matter most:

Hub-and-spoke. Agents never task one another. All output returns to the brain, which decides what happens next. This keeps the system auditable: every transition has one owner.
Gates are non-negotiable. Before any strategy advances, the brain checks the guardrails for that stage — overfitting detection, backtest verification, runtime loadability. A strategy that fails a gate is blocked, archived, or sent back, and a post-mortem is queued.

The brain also keeps a small persistent note (capped at 2000 characters) and a searchable set of self-judged lessons, so context and hard-won judgement carry across cycles. For the full account, see the brain.

The research daemon: the background loop

The research daemon is the autonomous loop that runs while you are away. Mechanically it is an async loop in the daemon process that does two jobs.

It drives research. Working through the brain, it invents hypotheses, spawns child strategies, runs them through the gauntlet, retires losers, and surfaces a shortlist. It is the engine behind hands-off operation.

It enforces live safety. The same daemon ingests live market prices (over WebSocket, with polling fallback), publishes shared price snapshots, and runs the hard risk controls in real time: the kill-switch, the daily-loss halt, and exchange reconciliation. These are the controls that flatten positions autonomously on a breach — no approval required.

The daemon is available to all beta users and does not require the agent layer, though agents make it far more effective. For depth, read the research daemon.

The scanner: live signal generation

The scanner is distinct from the daemon. Where the daemon ingests prices and guards risk, the scanner runs your database-backed strategies against live data, filters their signals by the current market regime, applies risk gates, and — only in live mode — places trades.

A useful way to hold the two apart:

Daemon = prices in, risk enforced, research driven.
Scanner = strategies evaluated, regime-gated signals out.

In beta, the scanner's execution path is hard-locked to paper. Real orders route to HyperLiquid, and live/mainnet is gated.

How a strategy travels the pipeline

The heart of Forven is the strategy lifecycle. The real stages, in order, are:

researching → backtesting → quick_screen → gauntlet → paper → live (live_graduated / deployed) → retired

The marketing site uses a simplified vocabulary. Bridged once: public "screen" is quick_screen, public "gauntlet" is gauntlet, public "candidate" is paper, and public "live" is live / live_graduated. Below we use the real names.

Stage	What it tests	Gate to advance
`researching`	A market thesis (a hypothesis) becomes a concrete strategy.	The idea compiles into a runnable strategy.
`backtesting`	Behaviour on historical data — Sharpe, profit factor, max drawdown, win rate, trade count.	Basic metrics look plausible.
`quick_screen`	Overfitting guardrails. Rejects implausible metrics and in-sample/out-of-sample divergence.	Pass the screen floors.
`gauntlet`	A robustness battery: walk-forward, parameter jitter, cost stress, regime split.	A high-enough robustness score and a clean verdict.
`paper`	Live signals, simulated execution, no capital at risk.	Operator approval (a capital-tier gate).
`live`	Real orders on HyperLiquid, under hard risk controls.	A second, stricter operator approval.
`retired`	End state. Archived manually or by the kill-switch.	—

A few things are worth stressing:

quick_screen is the triage gate. It is built to catch overfitting before it wastes compute: it rejects suspiciously perfect numbers (a Sharpe that is too high, a profit factor that is too high) because those usually signal a future-bar leak, not an edge.
gauntlet is the robustness battery. It is where most promising-looking strategies die. Surviving it means the edge held up out-of-sample and across stress — not that it will hold up tomorrow.
paper is mandatory. You cannot skip it, even with strong backtests. Paper validates live behaviour with no capital.
Capital transitions require a human. Promotion to paper and again to live pass through the approval queue by default. The brain queues them; it cannot approve them on its own.

For exactly what each gate checks and the thresholds involved, see the pipeline.

Local-first, auditable, BYOK

Three principles tie the design together:

Local-first. Your strategies, data, trades, and history live on your machine in FORVEN_HOME. Forven does not run your research in someone else's cloud.
Auditable. Every stage transition is logged with its rationale. The brain's lessons, the task audit log, and per-decision memos mean you can reconstruct why a strategy moved.
BYOK. The AI agent layer (the Forged tier) uses your own model-provider keys, held in the local keystore. Forven never resells model tokens.

What you'll see

Open the app and the home dashboard (/) is your operations view: system-health KPIs, the strategy leaderboard, the current regime, and a live activity stream. From there:

The lab (/lab) is the strategy development hub — backtest, run the gauntlet, read the verdict, promote.
Risk (/risk) shows the kill-switch, drawdown, and daily-loss state.
Brain (/brain) shows the orchestrator's autonomy state, recent actions, and working notes.
Ops (/ops) is the day-to-day operator home: pause the system, view scheduler jobs, read the soak report.

Steps: trace one strategy end to end

Get data. Open /data and download the OHLCV history for the symbol and timeframe you want to test.
Backtest. In the backtest studio (/backtest/new), pick a built-in strategy, set symbol/timeframe/dates, preview the signals, and submit. Read the result on the strategy detail page (/lab/strategy/[id]).
Run the gauntlet. From the lab, submit the strategy to the gauntlet and read the robustness verdict and the promotion-readiness checklist.
Promote to paper. Click Promote. The request lands in the approval queue (/approval); approve it to move the strategy to paper.
Watch it run. Monitor the paper session in /paper-trades. The scanner evaluates signals live; nothing touches real capital.

Live promotion is a further, gated step — and in beta builds it is hard-locked to paper regardless.

The pipeline — every stage and the gate to advance.
The brain — the sole orchestrator and its guardrails.
The research daemon — the autonomous background loop.
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