First run & setup

The first time Forven starts, it builds a single home directory for all of your state, seeds it with sample market data so the dashboard is useful immediately, and defaults execution to paper trading. This page explains exactly what is created, where it lives, and what to check before you start working.

If you have not cloned and started Forven yet, start with Install.

What happens on first launch

Forven bootstraps in a fixed order. Nothing here requires input from you — the app does it on startup — but knowing the sequence makes the first few minutes legible.

1. Forven resolves your home directory, FORVEN_HOME, defaulting to ~/.forven, and creates it if it is missing.
2. It seeds a .env (from .env.example on macOS/Linux when you copy it) so sane defaults are in place.
3. It copies a small set of OHLCV seed parquets into FORVEN_HOME/data/ohlcv, so the dashboard has real candles to show on first open.
4. It initializes the SQLite database (forven.db) at the current schema version and seeds the core agents.
5. The backend (FastAPI) starts and the scheduler registers its built-in jobs, each with a computed next-run time.
6. The frontend (SvelteKit on port 5173) loads and the dashboard renders against the seeded data.

The launcher does this for you. On Windows that is start_all.ps1; on macOS/Linux it is start_all.sh. Both create the virtual environment, install dependencies, initialize the database, and start the stack — see Install.

What you'll see

When the stack finishes starting, open http://127.0.0.1:5173 and the dashboard loads with seeded market data already present — candles, a populated symbol list, and a working chart. You will not see live positions or strategies yet; that is expected. A fresh install has data to explore but nothing trading. There is no login or account step.

Where your data lives

Everything Forven knows about lives under one directory, FORVEN_HOME (default ~/.forven). This is deliberate: it is local-first, it is easy to back up, and it is the only place credentials and history are kept.

~/.forven/
├─ config.json        # configuration (see the Configuration reference)
├─ forven.db          # main SQLite store (strategies, trades, tasks, KV)
├─ forven_lab.db      # backtest / lab database
├─ workspace/         # the 10 core .md files (operator profile, AI personality, lessons)
├─ data/ohlcv/        # market data, including the first-run seed parquets
└─ chromadb/          # vector memory store

The main database runs in WAL mode, so on disk you will also see forven.db-wal and forven.db-shm alongside forven.db. These three files are one database — back them up together.

One secret is stored outside FORVEN_HOME. The encryption key that protects your API keys and exchange credentials is written to a non-synced location: %LOCALAPPDATA%\Forven\.forven_key on Windows. This is intentional, so the key never follows a OneDrive or Dropbox sync. If you back up FORVEN_HOME, also keep that key paired with it, or encrypted values cannot be read back.

The setup wizard and operator profile

Forven keeps your operator profile in FORVEN_HOME/workspace/USER.md as structured YAML frontmatter — your timezone, starting capital, risk-per-trade, exchange, and notification preferences. The first-launch setup wizard collects these so the app can frame research around your context.

You can revisit any of this later in Settings; the wizard is just the first pass.

Capital and risk figures in your profile are inputs to a research process, not promises. They size illustrative scenarios — they do not predict outcomes.

Paper is the supported mode

Execution defaults to paper. Paper trades are recorded in SQLite only; no order ever reaches an exchange. Paper is the supported way to run Forven — optionally validated against the HyperLiquid testnet (no real funds).

There is no supported live / mainnet (real-money) path. The live code path exists in the engine, but wiring real exchange keys and switching to live is unsupported and entirely at your own risk. For the distinction between paper and live, see Execution modes.

FORVEN_EXECUTION_MODE = paper   (the default and supported mode)
FORVEN_ALLOW_MAINNET  = 0       (default-deny; mainnet is unsupported)

Returning from an older build (legacy home migration)

If you used a pre-rename build, your data lived in ~/.juddex or ~/.judex. On first run, Forven detects those directories and merges them into ~/.forven automatically, renaming database files in the process (for example juddex.db → forven.db). You do not need to move anything by hand.

A few things to know about the merge:

• Workspace files are mirrored back to the legacy ~/.juddex/workspace for compatibility. If a legacy copy has diverged, the merge keeps the longer text — so check your backup if a customization looks lost.
• Encrypted values depend on the encryption key. If you bring over an old FORVEN_HOME without its matching key, those secrets will not decrypt. Pair them.

First health check

Once the dashboard is up, do a quick sanity pass:

1. Confirm execution mode reads paper. Open the ops dashboard and check the execution-mode indicator. It defaults to paper, the supported mode.
2. Confirm seeded data is present. The dashboard chart should render candles from the seed parquets.
3. Glance at component health. The health monitor tracks the scheduler, data collector, and workers as green / amber / red and watches per-stream data freshness. Green across the board on a fresh install is normal; an amber on a data stream you have not backfilled yet is also normal.

If something is amber or red on first run, it is almost always a data stream that has not been collected yet — expected on a clean install, not a fault.

Caveats

• Paper is the supported mode. Execution defaults to paper; there is no supported live/mainnet path, and wiring real keys is at your own risk.
• The encryption key lives outside FORVEN_HOME and is not synced. Back it up alongside your data or you lose access to stored secrets.
• WAL means three files. Treat forven.db, forven.db-wal, and forven.db-shm as one unit when copying or backing up.
• A malformed USER.md frontmatter is tolerated — the app keeps the readable body and flags the parse error — but fix the YAML so your profile is applied.

A note on what Forven is

Forven is a research tool for building, testing, and killing trading strategies with discipline. It is not financial advice, it does not predict markets, and any numbers you see during setup or backtesting are illustrative. Survival through the research process is evidence of robustness, not a forecast of profit.

Related

• Install — clone the repo and run it on your own machine
• Settings — revisit your operator profile and preferences
• Operations & system controls — the day-to-day operator dashboard
• Configuration reference — config.json, precedence, and key groups