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 or desktop bundle to download — the launcher scripts set up 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. Besides the API, it hosts the scheduler, the headless agent and brain loops, and the data/risk daemon loop — so a plain install needs no other process.
• A SvelteKit frontend (served by Vite) on port 5173.
• SQLite for state, a Parquet data lake, and file-based quant skills, all under FORVEN_HOME (default ~/.forven).

Optional extras are the Discord bot, a separate daemon process, and the regime-lab worker. Custom and imported strategy code runs in its own locked-down worker process with no database, network, or secrets access.

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, runs a dependency preflight driven by pyproject.toml and installs any missing backend packages, installs the frontend dependencies, initializes the database, seeds the core agents, and starts the stack. It reads toggle variables from the current shell (it does not auto-load .env).

It is also the supervisor: it restarts a crashed service with backoff, can permanently disable a service that keeps crash-looping, and records every such decision in .tmp/logs/start_all.log. Each service's previous log is rotated aside rather than truncated, so the reason a service died survives its restart. start_all.bat is a double-clickable wrapper around 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 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. Because the defaults differ slightly between the scripts, set them explicitly rather than relying on them.

The Windows launcher window

On Windows, Forven Launcher.vbs opens a small desktop window (launcher.ps1) to start, stop, and restart the stack without a terminal, and scripts/build-launcher.ps1 compiles a native ForvenLauncher.exe host for it from scripts/ForvenLauncher.cs, using Windows' bundled .NET. The .exe is a local build output and is not in the repository. Both drive the same start_all supervisor and honor persistent stop markers under .tmp/. Process controls verify the installation path and process creation time, so the launcher never touches another checkout's processes. Stop and restart do not close exchange positions. See Install.

To validate the launcher without stopping live services:

powershell -NoProfile -File tests/test_launcher_services.ps1
powershell -NoProfile -STA -File launcher.ps1 -SmokeTest

First-run seeding

On first launch the stack bootstraps state under FORVEN_HOME:

• It resolves FORVEN_HOME (default ~/.forven) and creates it, falling back to a folder inside the repo if the default is not writable.
• It initializes the SQLite schema, applies migrations, and seeds the core agents.
• The data lake starts empty. Download markets from Data — Set up data offers presets, starting with BTC, ETH and SOL perps. The repository also carries a small BTC and ETH sample (1h, 4h, 1d) in packaging/config/seed_data; set FORVEN_DEFAULT_SEED_DATA to that folder and it is copied into a new FORVEN_HOME on first start.
• The scheduler registers its built-in jobs. The system starts in Manual mode, so none of them runs until you switch to Semi or Auto.

What you see in the app on first launch — the setup wizard and the banners — is covered in First launch & 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. There is no supported live path: the in-app switch only accepts paper, 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. The Windows launcher window is a convenience over the same scripts, not an installer.
• 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.
• Updating Forven — in-app updates and the GitHub webhook.
• First launch & setup — what the app shows on first launch.
• Environment variables — the complete variable reference.
• The CLI — python -m forven configuration and auth commands.