Skip to content
Open Net Worth Docs

Installing Open Net Worth

Supported platforms

macOS and Linux, natively. Windows via Docker or WSL2. The backend uses POSIX-only APIs in its data-write and process-management paths (file locking, process-group signals) — it won’t import on native Windows. On Windows, use Docker below, or WSL2 (a real Linux kernel) — not PowerShell or CMD directly.

Requirements

  • Python 3.12+ and Node.js 22+ — only if you’re installing outside Docker.
  • An AI provider key (Anthropic, OpenAI, or any OpenAI-compatible endpoint) if you want Lucius. The rest of the app — ledger, budgeting, investments — works without one; add a key later from Settings anytime.

You do not need to create a .env file. Every environment variable the app reads is optional — see Environment variables.

Option A — one command (recommended)

Terminal window
git clone https://github.com/open-net-worth-ai/open-net-worth
cd open-net-worth
make setup      # venv, backend + frontend deps, frontend build, DB migration — prints the URL
make start      # run it

make setup checks your Python/Node versions up front and fails with a clear message, not a traceback, if either’s missing. Safe to re-run anytime. Data lands at ~/.open-net-worth/ by default — outside the git checkout, so git clean, a hard reset, or re-cloning never touches it.

Once make start is running, open the URL it printed (http://localhost:8080 by default) and you’ll land on first run.

Option B — Docker

Terminal window
git clone https://github.com/open-net-worth-ai/open-net-worth
cd open-net-worth
docker compose up

The supported path on Windows, and works the same way on macOS/Linux if you’d rather not install Python/Node locally. It builds the frontend, runs database migrations, and serves the app on the port Compose reports, with data in a named volume that survives docker compose down.

Set a password before your first docker compose up — see Your first run § Docker for why Docker needs one where a bare-metal install doesn’t.

Option C — manual

The same steps as make setup, by hand, if you want full control or make isn’t available:

Terminal window
# Backend
python3 -m venv .venv && source .venv/bin/activate
pip3 install -r requirements.txt


# Frontend
cd frontend && npm ci && npm run build && cd ..


# Migrate the database
.venv/bin/python3 -c "from backend.db.migrate import ensure_migrated; ensure_migrated()"


# Run (serves the built frontend from frontend/dist/)
uvicorn backend.main:app --port 8080

Open http://localhost:8080.

See it with example data first

Want to look around before entering real numbers? make seed (or python3 -m backend.scripts.seed_examples --commit) populates a small, fabricated example dataset. It only fills stores that are still empty, so it’s safe to run even after you’ve started adding real data — it never overwrites anything.

Running it long-term

For day-to-day use, run the backend persistently rather than in a terminal you keep open. On macOS, make daemon-start installs it as a launchd service that restarts on crash and starts at login (make daemon-stop removes it). On Linux, run it under systemd, supervisord, or similar, pointed at make start. Docker handles this via Compose’s own restart policy.

Developing on it

Contributing code rather than just running the app? See CONTRIBUTING.md in the repo root for the dev-mode two-process setup (uvicorn --reload + npm run dev), the lint/type/test gate (make check), and the architecture rules.

A note on network access

By default, anyone with access to the machine — any local process, or you at the terminal — can reach the API with no password: trusting the loopback interface (localhost) is the deliberate default for a single-user app, not an oversight. A password starts to matter once you bind the server to your LAN, or under Docker — its bridge networking hides the loopback origin even though the published port itself stays bound to 127.0.0.1 by default (see Your first run § Docker). See I lost my password for what that default does and doesn’t protect.