Building from source

Forven ships as a single Windows desktop installer, but the installer is produced by an open build script you can run yourself. This page is for contributors and advanced users who want to build the packaged app locally, or who want to understand exactly what the installer contains and how it behaves on first run.

If you only want to install and use Forven, you do not need any of this — start with Install. This page assumes you have the source tree and are comfortable with PowerShell on Windows.

Forven is a research tool for building, testing, and killing trading strategies. Nothing about how it is built changes that: results from the lab describe past behavior under test, they are not predictive, and nothing here is financial advice.

What the packaged app is

The desktop app is a Tauri shell that bundles three things into one Windows installer:

• An embedded CPython 3.11 interpreter — the full backend runtime, so there is nothing for the user to install.
• The SvelteKit frontend, built to static assets.
• A small Rust shell (the Tauri host) that launches the backend and serves the interface.

The build produces an NSIS installer named Forven-Setup-x.y.z.exe. Installing it unpacks the embedded Python, the frontend, and a default configuration template, then the app self-bootstraps on first launch — see First run & setup.

There is one entry point for the whole build:

# From the packaging/ directory
.\scripts\build.ps1

Everything below is what that script orchestrates.

Before you start

• Windows. The packaged build targets Windows today. A macOS build is in progress.
• Toolchain. You need the Rust toolchain (for Tauri) and Node.js with npm (for the SvelteKit frontend) on PATH. Tauri's prerequisites apply.
• The source tree. Run from the packaging/ directory of the Forven repository; the build script and its config live there.
• Disk space. The output embeds a full CPython 3.11 runtime and ships with seed market data, so budget a few hundred megabytes for staging plus the installer.

What build.ps1 does

packaging/scripts/build.ps1 is the single orchestration script. It runs the build pipeline end to end and emits the installer. The stages, in order:

1. Freeze dependencies. Pin the backend's pip requirements into packaging/cache/requirements.txt so the embedded runtime installs a reproducible set.
2. Stage the interpreter. Extract the embedded CPython 3.11 interpreter into packaging/staging/python/.
3. Build the frontend. Run npm run build for the SvelteKit app; output lands in packaging/staging/dist/.
4. Configure the Tauri shell. Apply app metadata to the Rust host under src-tauri/.
5. Compile Tauri. Build the release binary into packaging/tauri/target/release/.
6. Emit the installer. The NSIS step assembles everything into Forven-Setup-x.y.z.exe under packaging/dist/.

The installer carries the embedded Python, the SvelteKit assets, and a baked-in environment template (see below) so a fresh install has sane defaults without any manual configuration.

Steps

To produce an installer from a clean checkout:

1. Open PowerShell in the packaging/ directory of the source tree.

2. Run the build:

   .\scripts\build.ps1

3. Wait for the pipeline to finish — it freezes deps, stages the interpreter, builds the frontend, compiles the Tauri shell, and runs NSIS.

4. Collect the installer from packaging\dist\Forven-Setup-x.y.z.exe.

5. Install it like any user would (the beta installer is unsigned, so expect a SmartScreen prompt — see Install).

What you'll see

A successful run leaves Forven-Setup-x.y.z.exe in packaging\dist\, with the staged interpreter and frontend in packaging\staging\. Running the installer extracts those into the install location; launching the app then performs the first-run bootstrap (home directory, seed data, schema init) described in First run & setup.

Baked-in defaults: default.env

The installer ships a default environment template at packaging/config/default.env. On a fresh install, this template is the source for the .env Forven seeds into FORVEN_HOME on first launch (via FORVEN_DEFAULT_ENV — packaged-app only). It is where the build sets the conservative, paper-only defaults a new user should start from.

Two packaged-app-only variables drive first-run seeding:

Both are set by the packaged build and are not something a user configures. The full variable list, including the startup and safety variables, lives in the environment variables reference.

The beta paper-lock is set at build time

This is the most important behavioral difference between a packaged build and a development run. The Rust launcher in the packaged app injects FORVEN_ENV=beta. That flag hard-locks execution to paper trading: any attempt to switch to live is rejected with a loud error, regardless of what config.json or environment variables say.

FORVEN_ENV            = beta     # set by the packaged Rust launcher
FORVEN_EXECUTION_MODE = paper    # beta builds always resolve to paper

In a development run from source, FORVEN_ENV is left unset, so the paper-lock is not applied by the build. The exchange layer still default-denies real-funds routing — FORVEN_ALLOW_MAINNET defaults to 0 and the HyperLiquid client defaults to testnet — but the build-level lock that guarantees paper in the shipped beta is a property of the packaged app, not of a source run. Treat any source build accordingly. The paper vs. live distinction is covered in Execution modes.

What first-run does after install

The installer is only half the story. The first time the installed app launches, it bootstraps state. In brief:

• It resolves FORVEN_HOME (default ~/.forven) and creates it.
• It seeds .env from FORVEN_DEFAULT_ENV (the baked-in default.env).
• It copies OHLCV seed parquets from FORVEN_DEFAULT_SEED_DATA into FORVEN_HOME/data/ohlcv.
• 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.

Running from source without packaging

You do not have to build an installer to run Forven from a checkout. On Windows, the source-run entry point is start_all.ps1, which performs the equivalent of the first-run bootstrap plus environment setup: it resolves FORVEN_HOME, creates a virtual environment, installs pip and frontend dependencies, initializes the database, and launches the backend, frontend, and optional services.

# From the repository root
.\start_all.ps1

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

In a source run the frontend dev server (Vite) comes up on port 5173, and the backend on FORVEN_PORT (default 8003). Because FORVEN_ENV is unset, the build-level paper-lock is not applied — see the caveat above.

Where things land

A quick map of the build's working directories under packaging/:

packaging/
├─ scripts/build.ps1     # the single build entry point
├─ config/default.env    # baked-in env template (seeds FORVEN_HOME/.env)
├─ cache/requirements.txt # frozen pip requirements
├─ staging/
│  ├─ python/            # extracted embedded CPython 3.11
│  └─ dist/              # built SvelteKit frontend
├─ tauri/target/release/ # compiled Tauri shell
└─ dist/Forven-Setup-x.y.z.exe  # the NSIS installer output

The build pipeline and installer specifics are documented in packaging/README.md in the source tree if you need to go deeper than this page.

Caveats

• The beta installer is unsigned. SmartScreen will warn on first run. This is a property of the certificate, not the contents — see Install.
• The paper-lock is a build property. It is injected by the packaged Rust launcher via FORVEN_ENV=beta. A source run leaves FORVEN_ENV unset, so do not rely on a from-source build to enforce paper — rely on the exchange-layer default-deny and FORVEN_ALLOW_MAINNET=0, and confirm your execution mode before trading anything.
• Windows-only for now. The packaged build targets Windows; macOS is in progress.
• Toolchain drift. The build depends on the Rust toolchain, Node/npm, and the embedded Python being present and compatible. If a stage fails, it is almost always a missing or mismatched toolchain rather than the app.

Related

• Install — download and run the packaged installer
• First run & setup — what the app does on first launch
• Environment variables — the complete variable reference