Environment variables

Forven reads a small set of environment variables to control where it stores data, which port it binds, the execution mode (paper by default), 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 launcher seeds a sensible .env on first run (on macOS/Linux you copy .env.example to .env), and the rest of configuration lives in the UI. Set these only when you need a non-default port or data location, are 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. Forven reads .env from the repository root (on macOS/Linux you copy .env.example to .env; on Windows start_all.ps1 reads variables from the current shell). 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

First-run seeding variables

These optional variables control what a fresh FORVEN_HOME is seeded with on first launch. Most users never set them — the launcher provides sensible defaults — but they are available if you want to point first-run seeding at your own .env template or parquet directory. See Running from source.

Startup script flags

These are read by the launcher (start_all.ps1 / start_all.sh) to decide which background processes to start.

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 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 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 by default, the supported mode), 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.
• Live/mainnet is unsupported. Paper (optionally on testnet) is the supported mode. Setting FORVEN_EXECUTION_MODE=live and FORVEN_ALLOW_MAINNET=1 is at your own risk and not a supported path.
• 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 is intended for local development only.

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