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 locks 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 installed the app 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. If this is a packaged install, it seeds a .env from the bundled template 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 UI loads and the dashboard renders against the seeded data.

You do not run these steps by hand in the desktop app — they happen during the first-launch bootstrap. If you are running from source on Windows, the equivalent is start_all.ps1, which performs the same sequence plus environment setup.

What you'll see

When the app finishes starting, your browser opens to the dashboard with seeded market data already loaded — 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.

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.

The beta paper-lock

Beta builds hard-lock execution to paper. Paper trades are recorded in SQLite only; no order ever reaches an exchange. This is enforced at the build level — the packaged app sets FORVEN_ENV=beta, and any attempt to switch to live is rejected with a loud error regardless of what config.json or environment variables say.

In plain terms: during beta you cannot accidentally trade real money. The execution-mode toggle exists, but in a beta build it stays on paper. For the distinction between paper and live, see Execution modes.

FORVEN_EXECUTION_MODE = paper   (beta builds always return paper)
FORVEN_ENV            = beta     (set by the packaged app; hard-locks paper)

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. In beta it will say paper and cannot be changed.
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

• Beta is paper-only. You cannot switch a beta build to live trading; the lock is intentional.
• 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 — download and set up the desktop app
• Settings — revisit your operator profile and preferences
• Operations & system controls — the day-to-day operator dashboard
• Configuration reference — config.json, precedence, and key groups