Environment variables

Forven reads a small set of environment variables to control where it stores data, which port it binds, whether trading is locked to paper, and how the local HTTP API is secured. This page is the authoritative reference: every variable, what it does, and its default.

Most users never set these by hand. The desktop installer seeds a sensible .env on first run, and the rest of configuration lives in the UI. Set these only when you are running from source, hardening a non-localhost deployment, or wiring up an integration.

How variables are resolved

Environment variables sit at the top of Forven's configuration precedence:

env var  >  KV store (settings)  >  config.json  >  built-in default

So an env var always wins over the same value set in the configuration file or the in-app settings. In the packaged desktop app, the first-run wizard seeds FORVEN_HOME/.env from a baked-in template; in a source checkout, Forven reads .env from the repository root. See Configuration reference for the file-level structure.

On Windows, set a variable for the current PowerShell session like this:

$env:FORVEN_PORT = "8003"
$env:FORVEN_BIND_HOST = "127.0.0.1"

To persist a value, add it to your .env file (one KEY=value per line) rather than exporting it each session.

Startup & paths

These control where Forven lives and how it listens.

FORVEN_HOME is the single most important variable: point it at a different directory to run an isolated second instance, or to relocate your data. Everything Forven knows lives under it.

Safety: execution mode & mainnet gate

These two variables, together with the build channel, decide whether Forven can ever touch real capital. Treat them as the load-bearing safety surface.

The public docs sometimes call the paper stage a candidate strategy; internally and in these variables it is always paper.

API authentication

Forven's local HTTP API binds to 127.0.0.1 by default and is unauthenticated unless you set keys. For any deployment that is not strictly localhost, set keys and require them. See the full REST & WebSocket API reference for endpoint groups and headers.

When a key is unset, Forven logs a loud warning at startup. Setting FORVEN_AUTH_REQUIRED=true turns that warning into a hard failure — recommended for anything reachable beyond loopback.

$env:FORVEN_API_KEY = "<a-long-random-string>"
$env:FORVEN_OPERATOR_KEY = "<a-different-long-random-string>"
$env:FORVEN_AUTH_REQUIRED = "true"

Encryption & secrets

Forven encrypts API keys and exchange credentials at rest using Fernet symmetric encryption. The key is generated once and stored in a non-synced location.

The auto-generated key lives at %LOCALAPPDATA%\Forven\.forven_key on Windows (~/.config/forven/.forven_key elsewhere) — deliberately outside FORVEN_HOME.

HyperLiquid credentials

These provide live-routing credentials as an environment override for file-based or encrypted-settings storage. They are only consulted when execution mode is live. Full setup is on the HyperLiquid integration page; keys stay on your machine.

Credentials are resolved from your encrypted in-app settings (Settings → HyperLiquid) first, then these env vars, then a legacy file-based settings.json. Note that FORVEN_HL_USE_TESTNET=false still does not permit real-funds orders on its own — FORVEN_ALLOW_MAINNET=1 is the separate, explicit gate.

Integrations

Packaged-app-only variables

The Rust launcher and first-run wizard set these inside the installed desktop app. You do not set them by hand on a normal install; they exist so a fresh install has data and a paper lock from the first launch. See Building from source for how they are baked in.

Startup script flags

These are read by the source-checkout launcher (start_all.ps1) to decide which background processes to start. They do not apply to the packaged app.

Runtime tuning (advanced)

You rarely need these. They size worker pools and timeouts; the defaults are tuned for a desktop machine. Stay within the documented bounds.

Verifying your settings

After setting variables, confirm the backend picked them up:

1. Start Forven (the desktop app, or start_all.ps1 from a source checkout).
2. Open http://127.0.0.1:8003/api/health — it should return a health payload with no auth required.
3. Check the /ops page for the active execution mode and system health.
4. If you set auth keys, confirm a request without the key is rejected with 401.

What you'll see: the /ops dashboard shows the current execution mode (it should read paper on a beta build, regardless of any env override), system health, and scheduler status. If a key is required and missing, every operator-gated call returns 401.

Caveats

• Env always wins. A value set here overrides the same key in the UI or config.json. If a setting in the app "won't stick," check for an env override first.
• Beta cannot go live. No combination of variables unlocks live trading in a beta build. The paper lock is enforced at read time.
• Secrets and their key can diverge. Back up FORVEN_HOME/auth.json together with the non-synced encryption key (or pin it via FORVEN_ENCRYPTION_KEY).
• Webhook endpoint is dev-only. FORVEN_GITHUB_WEBHOOK_SECRET has no effect in packaged builds.

Forven is a research tool. Nothing here is financial advice, paper results are not predictive of live results, and any numbers in the app are illustrative of process — not a forecast of profit.

Related

• Configuration reference — config.json structure and the full precedence chain
• REST & WebSocket API — endpoints, headers, and the auth model these keys back
• HyperLiquid integration — credential setup and testnet/mainnet selection
• Execution modes: paper vs live — what the safety variables actually gate