Environment variables

Forven reads environment variables to control where it stores data, which ports it binds, whether real-funds (mainnet) orders are ever allowed, how the local HTTP API is secured, and a handful of advanced tuning knobs. This page is the reference: each variable, what it does, and its default.

Most users never set these. Nearly all configuration lives in the app's Settings. Reach for an environment variable only when you need a non-default port or data location, are hardening a deployment beyond localhost, are wiring an integration, or are pinning a value so the UI can't change it.

How variables are resolved

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

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

So an environment variable always wins over the same value set in the app or in the configuration file. If a setting "won't stick" in the UI, check for an environment override first.

The backend does not read a .env file by itself; the launcher is what puts variables into its environment:

• macOS / Linux: start_all.sh loads .env from the repository root if it exists. Copy .env.example to .env and edit it.
• Windows: start_all.ps1 reads variables from the shell that runs it. It does not load .env.

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

$env:FORVEN_PORT = "8003"
$env:FORVEN_BIND_HOST = "127.0.0.1"
.\start_all.ps1

To make a value stick across sessions on Windows, store it as a user environment variable and open a new terminal:

[Environment]::SetEnvironmentVariable("FORVEN_PORT", "8003", "User")

Startup & paths

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. Keep FORVEN_DATA_DIR and FORVEN_HOME consistent — if they disagree, the backend logs a prominent startup error, because enrichment data (funding, open interest, macro) would be read from the wrong place.

Safety: the mainnet gate & execution mode

FORVEN_ALLOW_MAINNET is the one variable that decides whether Forven can ever place a real-funds order. Treat it as the load-bearing safety surface.

What actually sends orders to HyperLiquid is a strategy at the Live stage (live_graduated) or a Bot Factory bot armed live. Paper-stage strategies fill locally, inside Forven, and never place an order. Those live orders go to testnet unless you switch Settings → HyperLiquid → Hyperliquid testnet off (a change that needs a typed LIVE to save) and set FORVEN_ALLOW_MAINNET=1.

The public site sometimes calls the paper stage a candidate strategy; in the app and in these variables it is always paper.

API authentication

Forven's local HTTP API binds to 127.0.0.1 and is unauthenticated unless you set keys. On loopback that is safe for a single user. For anything else, set both keys. See the REST & WebSocket API for endpoint groups and headers.

Two guards fail closed:

• Non-loopback bind. If FORVEN_BIND_HOST (or FORVEN_HOST) is anything other than a loopback address, the backend refuses to start unless both FORVEN_API_KEY and FORVEN_OPERATOR_KEY are set. The API can run code and manage orders; it is never exposed to a network unauthenticated.
• FORVEN_AUTH_REQUIRED=true turns the startup warning about missing keys into a hard failure.

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

Encryption & secrets

Forven encrypts provider keys and exchange credentials at rest with Fernet symmetric encryption.

The generated key lives at %LOCALAPPDATA%\Forven\.forven_key on Windows ($XDG_CONFIG_HOME/forven/.forven_key or ~/.config/forven/.forven_key elsewhere) — deliberately outside FORVEN_HOME and outside cloud-synced folders. A key left over in FORVEN_HOME by an older version is migrated there. Forven refuses to generate a fresh key when encrypted data already exists, because a new key would orphan every saved credential.

HyperLiquid credentials

These supply exchange credentials as a fallback for the encrypted in-app settings. They matter for Live-stage strategies and live-armed bots — paper fills never place an exchange order. Full setup is on the HyperLiquid integration page; keys stay on your machine.

Credentials resolve from the encrypted in-app settings (Settings → HyperLiquid) first, then these variables, then the legacy file store. Once the in-app settings exist they win, including the Hyperliquid testnet toggle. Turning testnet off does not permit real-funds orders on its own — FORVEN_ALLOW_MAINNET=1 is the separate, explicit gate.

AI, agents & strategy code

API keys for model providers are not environment variables — connect providers on the Agents page (Setup → Providers), where they are encrypted at rest.

Bot sandbox (Windows)

Run python -m forven bot-sandbox to prepare and check the sandbox. If it is unusable on your machine, bots start without it and the bot's activity log says why.

Regime gate

The direction × regime gate is normally configured on the risk page or in Settings → Trading → Regime gating. These override it.

Integrations & updates

MCP server

The MCP server is a separate process spawned by your MCP client, so these go in the client's env block, not the backend's environment.

Backups & logs

First-run seeding

These control what a fresh FORVEN_HOME is seeded with on its first launch. Most users never set them. See Running from source.

Launcher flags

The launch scripts read these to decide which processes to start. The defaults differ by script, so check which one you run.

"Windows launcher" means ForvenLauncher.exe / Forven Launcher.vbs (see Installing Forven); start_all.bat uses the same daemon default. START_BOT=1 without DISCORD_TOKEN skips the bot with a warning.

Runtime tuning (advanced)

You rarely need these. They size worker pools and timeouts; the defaults suit a desktop machine, and most have an in-app equivalent set by the throughput preset.

Verifying your settings

After setting variables, confirm the backend picked them up:

1. Start Forven with the launcher (start_all.ps1 on Windows, start_all.sh on macOS/Linux).
2. Open http://127.0.0.1:8003/api/health — it returns a health payload with no auth required.
3. Open Diagnostics in the app for the health checks, and look at the control strip at the top of any page: with nothing at the Live stage it reads Mode: PAPER and a TESTNET badge. Live ×N means N strategies or bots can send real orders.
4. If you set auth keys, confirm that a request without the key is rejected with 401.

Caveats

• Env always wins. A value set here overrides the same key in the app or config.json.
• Windows doesn't read .env. Set variables in the shell, or as user environment variables.
• Live/mainnet is unsupported. Paper is the supported mode. Setting FORVEN_ALLOW_MAINNET=1 and promoting a strategy to Live is at your own risk.
• Secrets and their key can diverge. Back up FORVEN_HOME/auth.json together with the encryption key, or pin it with FORVEN_ENCRYPTION_KEY.
• Exposing the API needs both keys. A non-loopback bind without them refuses to start, by design.

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
• Updating & backups — the in-app updater and database snapshots
• Execution modes: paper vs live — what the safety variables actually gate