Install

Forven is free and open source and you self-host it: you clone the source repository, run one script, and it builds 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 covers getting Forven running from source. What happens the first time it starts — where your data lives, seed data, the supported paper mode — is covered in First run & setup.

Before you start

You need three things on your machine:

• Python 3.11+ — the backend is FastAPI/uvicorn.
• Node.js — the frontend is SvelteKit (built and served by Vite).
• git — to clone the repository.

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 your own 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, optionally validated against the HyperLiquid testnet — see First run & setup.

Clone the repository

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

Everything below runs from the repository root.

Run it

The launcher scripts do the heavy lifting: they create a virtual environment, install backend and frontend dependencies, initialize the database, and start the stack.

Windows (easiest)

powershell -ExecutionPolicy Bypass -File .\start_all.ps1

start_all.ps1 creates .venv, installs the backend (pip install -e .) and frontend (npm install) dependencies, initializes the SQLite database, and starts the backend, frontend, and optional services.

To skip the optional Discord bot and the background daemon on first run, set these in the same shell before launching:

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

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, then starts the stack. START_BOT=0 and START_DAEMON=0 skip the Discord bot and the background daemon — drop them once you want those services.

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:

# Should return ok
curl http://127.0.0.1:8003/api/health

Then open http://127.0.0.1:5173 in your browser. The dashboard loads with seeded OHLCV market data already present, so the charts and leaderboard are not empty on a fresh install. There is no login or device-code step — you go straight to the lab.

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 is needed only if you turn on the agent layer. Add one from the CLI, for example:

  python -m forven auth login openai

  You bring your own provider account and pay that provider directly. Forven never resells tokens and never sees your key on any server — it stays in your local keystore. See Models & providers (BYOK).

• Exchange (testnet) keys are needed only if you want to exercise the HyperLiquid integration against the testnet (no real funds). They live in environment variables, ~/.forven/hyperliquid.json, or encrypted settings — never sent anywhere but the exchange. The supported mode is paper, optionally validated on testnet; there is no supported live/mainnet path.

The CLI

python -m forven launches the CLI (not the API server). Useful commands:

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

Where your data lives

Forven stores everything under a single root directory — your FORVEN_HOME, which defaults to ~/.forven. That one folder holds your configuration, the SQLite databases, your workspace files, and the local vector memory. Nothing is written to a remote server.

# Default data root
~/.forven

First run & setup walks through exactly what gets created on first launch.

Optional: change the port or data location

The defaults work for most people. If port 8003 is taken, or you want your data on another drive, override 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, including safety and trading variables, lives in the environment variables reference. For most users, the defaults are correct and you can skip this entirely.

After installing

• First run & setup — what happens on first launch: your data directory, seed data, the setup wizard, and the supported paper mode.
• Quickstart — the concrete path from a fresh clone to your first paper strategy.

Caveats

• Self-hosted from source. Forven is not distributed as a downloadable .exe or desktop installer. You clone the repo and run the launcher.
• Bring your own keys. Any LLM or exchange credentials you supply stay on your machine and are never sent to a Forven server.
• Paper (and testnet) is the supported mode. You cannot route real orders on a supported path; live/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

• First run & setup
• Quickstart
• License — Forven is free and open source under AGPL-3.0-or-later.