Updating Forven

Forven is run from a git checkout, so updating means moving that checkout to the latest code and restarting onto it. You can do that from inside the app, by hand, or automatically on every push. This page covers all three, what happens to your data on the way, and the behavior changes worth knowing about.

Forven is a research tool. Updates can change how strategies are measured and validated; nothing here is financial advice.

Before you update: back up

Forven backs up its database for you — a daily scheduled snapshot, plus an automatic snapshot before any schema migration runs, both under FORVEN_HOME/backups/database with bounded retention. A manual copy before a big jump is still cheap insurance:

# Default location of the main database
cp ~/.forven/forven.db ~/.forven/forven.db.bak-$(date +%s)

The database runs in WAL mode: if you copy it by hand while Forven is running, also copy forven.db-wal and forven.db-shm, or stop Forven first.

In-app updates

Settings → System → Software updates shows your Current version, the Branch you are on, and when Forven Last checked. The status line reads Up to date., Update available — N commits behind origin/main., or This install can't self-update. with the reason.

The app checks at startup and then once a day. When the tracked branch is ahead, a banner at the top of every page reads Update available — N commits behind with the latest commit's subject, and offers Update & restart — or Open Settings when the update is blocked. ✕ hides it for this session, until a newer commit lands.

• Check for updates compares your checkout with the tracked remote branch (origin/main by default).
• Update & restart fast-forwards the checkout (git fetch + git pull --ff-only) and then restarts the backend onto the new code. The start_all supervisor owns the restart, so it only works when Forven was started with start_all (or the Windows launcher). You see Updating… and then Restarting…, and the page reloads when the backend is back.

The updater never rewrites your state. It refuses — with a clear reason — when:

• your working tree has uncommitted changes,
• your checkout has local commits the remote doesn't have, or
• you are on a different branch.

Both update endpoints (GET /api/system/update/check, POST /api/system/update/apply) are operator-gated. To track something other than origin/main, set FORVEN_UPDATE_REMOTE and FORVEN_UPDATE_BRANCH.

Updating by hand

git pull --ff-only

Then restart. On Windows, rerun start_all.ps1 with a clean restart:

$env:FORCE_RESTART = '1'
powershell -ExecutionPolicy Bypass -File .\start_all.ps1

start_all re-checks your Python dependencies against pyproject.toml on every start and installs anything new. On macOS/Linux, re-run python -m pip install -e . and npm install in frontend/ if the update added dependencies, then bash start_all.sh.

Automatic updates on push (optional)

For a server you manage, Forven can pull on every GitHub push. Point a GitHub webhook at POST /api/webhooks/github and set:

Only push events for the configured branch pull, and the pull is fast-forward only. GET /api/webhooks/github/health confirms the configuration.

What happens on first boot after an update

• Schema migrations apply themselves. They run once, are tracked, and are skipped if already applied — after a pre-migration database snapshot. No manual step.
• Stale verdicts re-run. Every validation verdict is stamped with the backtest engine version and the data semantics it was scored on. When an update changes how metrics are computed, older verdicts become stale and are re-queued automatically — expect a burst of re-validation. Stale evidence is never counted against a strategy. See promotion gates.
• Paper evidence restarts cleanly. When the paper engine itself is corrected, your paper book's go-live is stamped to the upgrade moment, so the corrected engine records trades from then on instead of replaying history — and the paper → live gate only counts trades recorded by the current engine. A strategy that looked nearly ready will need to rebuild paper evidence. That is deliberate: nothing should reach real money on numbers from an engine that was wrong.
• Custom strategies are migrated where it is safe. For example, custom strategies that imported indicator helpers from forven.scanner are rewritten to import them from forven.strategies.indicators.

Updating past October 2026

The first boot on an October 2026 build changes a few things once. Each step runs a single time and is recorded, so a later restart repeats none of them:

See promotion gates for the deflated-Sharpe gate and the held-back test.

The gate-plan update

A later October 2026 update changes how strategies reach paper and live. Paper risks no capital, so the door into paper now stops only strategies that are broken or clearly losing; the selection-bias checks (deflated Sharpe, walk-forward fold rate, regime split, jitter, the held-back test) are recorded there and enforced at paper → live, where capital is at stake. On an existing install:

• New settings take their defaults. The door into paper, the paper pool, the live-gate evidence rule, the quick-screen rule, the daily agent registration cap and the automatic search grid need no migration; the rest of your stored settings are kept. See configuration.
• Strategies already in paper move to the new rules. From the first hourly pool pass they can be retired by its rules, and the paper → live gate judges them with the sequential forward-evidence test and the breadth test. One whose breadth test reads general may start paper-trading extra coins.
• Live strategies are never touched. A one-off, report-only re-check against the new live gate runs on the first pool pass; read it with python -m forven.agent live-recheck.
• The held-back period shrinks once. A stored lag_quarters of 2 becomes 1, so a quarter of data goes back to research, and the log says Gate plan: research holdout now holds back 1 quarter(s) instead of 2. Set it back to 2 in Settings → Lab → Research and it stays.
• Recent archives aren't re-run on their own. python -m forven.agent readmit-candidates --days 30 lists strategies the old door stopped that the research door would admit. python -m forven.agent requeue <ids> sends the ones you pick back to the quick screen for a fresh gauntlet run under today's settings.
• Two new jobs appear on Agents → Schedules: forven-paper-pool-tick (hourly) and forven-weekly-funnel-report (Mondays). See scheduler.

To keep the old gates, choose Strict paper (Settings → Lab → Door into paper), Strict quick screen (Quick-screen rule) and Fixed floors (pre-plan) (Live gate evidence rule). The three are separate settings.

Behavior changes to expect

A few changes from the 2026 releases are worth knowing, because they can look like new problems:

• More alerts, not more faults. A hung scanner or frozen daemon now goes red and alerts; stale data blocks new entries; orphan exchange positions get an emergency stop. New alerts are the system working.
• More timeframes trade. Strategies on timeframes that previously never fired in paper (30m, 2h, 8h, 12h, and others) may start trading.
• Self-fetching custom strategies are refused. A custom strategy that fetches its own market data inside the strategy (from forven.data, forven.data_manager, or forven.scanner) no longer loads — the sandbox cannot supply a second asset's series. Rework it to take its data from the engine.
• Mainnet requires an agent wallet. If you run the unsupported live path on mainnet, a master-account private key is refused; use a HyperLiquid API (agent) wallet.
• Live concurrency default is 5. A stored live max_concurrent_positions of exactly 1 (the old default) was migrated to 5; a value you set yourself is untouched.
• Retired features. The Memory Bank page (and its ChromaDB store), the Execution Trader agent, the Portfolio screen, crucibles and hypotheses, and the Parked stage were removed. See what's new.

Optional clean-ups

After a major engine correction you may want to clear old paper trades from view and re-score stored metrics. These scripts are optional and run from the repository root:

python scripts/reset_paper_trades.py            # dry run: shows what would be cleared
python scripts/reset_paper_trades.py --apply    # backs up, then clears paper trades (keeps live trades)

Pause the paper service (or stop the daemon) before --apply, so a new paper trade does not open mid-reset. Bulk re-scoring (scripts/rescore_paper_strategies.py --apply) re-downloads data per strategy and can take hours — run it overnight, or simply re-run backtests for the strategies you care about.

Related

• What's new — the notable changes by month
• Install — the launcher and supervisor
• Database & maintenance — backups, retention, and factory reset
• Environment variables — update and webhook variables