Running from source

Forven is self-hosted from source: you clone the repository and run it on your own machine. There is no packaged installer, no .exe, and no desktop bundle to download — the launcher scripts build and start everything locally. This page goes a level deeper than Install: what the launcher does, the optional-service toggles, and how first-run seeding works.

If you only want to get Forven running, Install is the short version. This page is for contributors and anyone who wants to understand the moving parts.

Forven is a research tool for building, testing, and killing trading strategies. Results from the lab describe past behavior under test, they are not predictive, and nothing here is financial advice.

What you run

Forven is a server-first stack you start on localhost:

• A FastAPI backend (uvicorn) on port 8003, with health at http://127.0.0.1:8003/api/health.
• A SvelteKit frontend (built and served by Vite) on port 5173.
• SQLite for state and a ChromaDB-backed memory layer, all under FORVEN_HOME (default ~/.forven).

There is one entry point per platform — the launcher script — and it handles environment setup, dependency install, database init, and process startup.

Prerequisites

• Python 3.11+ — the backend runtime.
• Node.js (with npm) — for the SvelteKit frontend.
• git — to clone the source.

Run it

From a clean clone (git clone https://github.com/judder659/forven.git && cd forven):

Windows

powershell -ExecutionPolicy Bypass -File .\start_all.ps1

start_all.ps1 creates .venv, installs missing backend (pip install -e .) and frontend (npm install) dependencies, initializes the database, and starts the stack. It reads toggle variables from the current shell (it does not auto-load .env).

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 in the repo root, then starts the stack.

Run the parts individually

You can also start the backend and frontend separately during development:

# Backend only
python -m uvicorn --app-dir . forven.api:app --host 127.0.0.1 --port 8003 --reload

# Frontend only
cd frontend
npm run dev

Optional-service toggles

The launcher reads a handful of environment variables that decide which optional services start. These are convenience switches for a source run, not user-facing config:

For a quiet first run, set START_BOT=0 and START_DAEMON=0 to skip the Discord bot and the background daemon.

First-run seeding

On first launch the stack bootstraps state under FORVEN_HOME:

• It resolves FORVEN_HOME (default ~/.forven) and creates it.
• It seeds a .env with sane, paper-only defaults (on macOS/Linux you copy .env.example to .env).
• It copies OHLCV seed parquets into FORVEN_HOME/data/ohlcv so the dashboard shows data immediately.
• It initializes the SQLite schema and seeds the core agents, then starts the backend and scheduler.

The full sequence — including legacy home migration and the first health check — is documented in First run & setup.

Environment and safety

Start from .env.example and only set what you need. Values worth knowing:

• FORVEN_EXECUTION_MODE=paper — the default and supported mode.
• START_BOT=0 / START_DAEMON=0 — unless you intentionally want those services.
• FORVEN_API_KEY / FORVEN_OPERATOR_KEY — if the API will be reachable beyond localhost.
• FORVEN_ENCRYPTION_KEY — to encrypt stored credentials at rest.
• FORVEN_HOME — to put runtime state outside the default ~/.forven.

The supported way to run Forven is paper mode, optionally validated against the HyperLiquid testnet (no real funds). There is no supported live/mainnet path: do not enable live or mainnet casually — the exchange layer default-denies real-funds routing (FORVEN_ALLOW_MAINNET=0), and wiring real keys is at your own risk. See Execution modes.

The full variable list lives in the environment variables reference.

Quality checks

If you are contributing, the same checks CI runs:

python -m pytest tests -q
python -m ruff check forven tests

cd frontend
npm test
npm run check

Caveats

• Self-hosted, not packaged. Forven is run from source. There is no .exe/installer build path.
• Paper is the supported mode. A source run leaves execution at paper by default; confirm your execution mode before doing anything with exchange keys.
• Toolchain drift. The stack depends on Python 3.11+ and Node/npm being present and compatible. If startup fails, it is almost always a missing or mismatched toolchain.

Related

• Install — the short version: clone and run.
• First run & setup — what the app does on first launch.
• Environment variables — the complete variable reference.
• The CLI — python -m forven configuration and auth commands.