Install

Forven is free and open source and you self-host it: you clone the source repository, run one launcher, and it sets up and starts the whole stack on your own machine. There is no account to create, no installer to download, and no license key — every feature is free under AGPL-3.0-or-later.

This page gets Forven running. What you see the first time it opens — the setup wizard and the banners a fresh install shows — is covered in First launch & setup. Keeping it up to date is covered in Updating Forven.

Before you start

You need three things on your machine:

• Python 3.11+ — the backend is FastAPI/uvicorn.
• Node.js (with npm) — the frontend is SvelteKit, served by Vite.
• git — to clone the repository, and later to update it.

You do not need a Forven account, a downloaded app, or a license. You bring your own LLM provider key (only if you use the optional agent layer) and, optionally, exchange testnet keys — both stay local and are never sent to any Forven server.

This is a research tool. Forven helps you build and stress-test trading strategies. It does not predict markets, and nothing in these docs is financial advice. The supported way to run it is paper trading.

Clone the repository

git clone https://github.com/judder659/Forven.git
cd Forven

Everything below runs from the repository root.

Run it

Windows

$env:START_BOT = '0'
$env:START_DAEMON = '0'
powershell -ExecutionPolicy Bypass -File .\start_all.ps1

start_all.ps1 is also the supervisor. It creates .venv, checks your backend dependencies against pyproject.toml and installs anything missing, installs the frontend dependencies, initializes the SQLite database and seeds the core agents, then starts the backend and frontend — and restarts a service that crashes, with backoff. Logs go to .tmp/logs/.

START_BOT=0 skips the optional Discord bot, and START_DAEMON=0 skips a separate daemon process — the backend already hosts the data and risk loop in-process, so you don't need it. Set either to 1 when you want it.

macOS / Linux

python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip && python -m pip install -e .
cd frontend && npm install && cd ..
cp .env.example .env
START_BOT=0 START_DAEMON=0 bash start_all.sh

start_all.sh loads .env if it exists, checks your Python dependencies (and runs pip install -e . once if any are missing), then starts the backend and frontend. Press Ctrl+C to stop everything it started. The .env copied from .env.example holds the safe defaults: paper execution, Hyperliquid testnet, localhost binding, the shell tool off.

What you'll see

When the stack is up, the backend listens on http://127.0.0.1:8003 and the frontend on http://127.0.0.1:5173. Confirm the backend is healthy:

# Returns a JSON health summary
curl http://127.0.0.1:8003/api/health

Then open http://127.0.0.1:5173. There is no login or device-code step. A fresh install looks like this:

• The setup wizard opens over the dashboard: Welcome, Trading basics, AI providers, Notifications, Done. Every step can be skipped. Finish or Skip all — I'll configure later marks it complete; closing it with ✕ does not, so it opens again next time.
• Manual mode. The system starts in Manual: all autonomous background work is frozen until you switch to Semi or Auto in the control strip. See autonomy modes.
• Paper, on testnet. The control strip reads Mode: PAPER and TESTNET.
• "Trading halted: startup exchange recovery active …" appears while no Hyperliquid credentials are set. It is about the exchange connection that live orders use: backtests, the gauntlet and paper trading work anyway. See troubleshooting.
• An empty data lake. Nothing is downloaded yet. On Data, Set up data → then Set up Starter fetches BTC, ETH and SOL perps (1h, 4h and 1d, all history) in about a minute — see Get your first market data.

Windows desktop launcher

On Windows you can run Forven from a small desktop window instead of a terminal. It gives you Start Forven, Stop Forven, Restart Forven, per-service rows for the backend and frontend, live status, recent supervisor activity, and Open Forven to open the app.

• Forven Launcher.vbs in the repository root opens the launcher straight away, no build needed.

• ForvenLauncher.exe is a native host for the same launcher window. It is not in the repository — you build it once from scripts/ForvenLauncher.cs, using Windows PowerShell and the .NET that ships with Windows. Nothing is downloaded:

  powershell -ExecutionPolicy Bypass -File .\scripts\build-launcher.ps1

  The script writes ForvenLauncher.exe to the repository root. It refuses to overwrite an existing one: to rebuild, close the launcher and delete the old .exe first. Keep the .exe in the Forven folder, and make a desktop shortcut to it if you like.

The launcher is independent of the running app — opening or closing it changes nothing. Stop and Restart interrupt in-flight work and trade monitoring, but they do not close exchange positions; the launcher warns you before either. Stop records a persistent stop intent, so a watchdog won't bring services back until you Start again. The launcher only controls this installation's own processes — it verifies the install path and never kills an unrelated Python process.

This is not an installer: you still clone and run Forven from source. The launcher is a convenience window over the same start_all supervisor.

Bring your own keys

Forven runs the full local research lab — data, backtesting, the gauntlet, and paper trading — with no keys at all. Two kinds of key are optional, both local-only:

• An LLM provider key, only if you use the agent layer. Connect it in the setup wizard or under Agents → Setup → Providers — paste a key, or sign in with OAuth for OpenAI or MiniMax:

  python -m forven auth login openai
  python -m forven auth status

  A key that only sits in an environment variable is not enough to spend with: Forven calls a model only when its provider is connected in the app and the model is selected — on the Shortlist, or picked for an agent, a fallback or the backup model under Agents → Setup → Agent models. See Models & providers (BYOK).

• HyperLiquid testnet keys, only if you want to exercise the HyperLiquid integration without real funds. Enter them in Settings → HyperLiquid. Paper trading does not need them — it runs on public Binance market data.

Where your data lives

Forven stores everything under one directory — your FORVEN_HOME, which defaults to ~/.forven. It holds your configuration, the SQLite databases, your workspace files, the quant-skills store, and the market-data lake. Nothing is written to a remote server.

Optional: change the port or data location

If port 8003 is taken, or you want your data on another drive, set a few environment variables before launch:

# Bind the backend to a different port
$env:FORVEN_PORT = "8010"

# Put all app state somewhere other than ~/.forven
$env:FORVEN_HOME = "D:\forven"

The complete list lives in the environment variables reference.

After installing

Caveats

• Self-hosted from source. Forven is not distributed as an installer or packaged desktop app. You clone the repo and run the launcher; the optional Windows launcher window is built from the source in the repo.
• Bring your own keys. Any LLM or exchange credentials you supply stay on your machine.
• Paper is the supported mode. Live trading on mainnet is unsupported and at your own risk. See Execution modes.

Forven is a research tool. Results from the lab describe a strategy's past behavior under test; they are not predictive, and nothing here is financial advice.

Related

• Running from source — the services, toggles, and launcher internals
• Troubleshooting & recovery — the fresh-install warnings and common faults
• License — Forven is free and open source under AGPL-3.0-or-later.