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 track, and when Forven last checked. The app also re-checks once a day and shows an update available banner at the top of the page.

• 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). The page shows Updating… and then Restarting….

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.

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, and the Portfolio screen 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