Skip to content
Open Net Worth Docs

Installing Open Net Worth

There are three ways to run Open Net Worth. Pick one:

Best forYou need
A. Desktop app (recommended)Using it on your own computerNothing else — it bundles everything
B. Server with onwAn always-on machine you open from a browser or from the desktop app on other devicesA terminal
C. DockerA home server or NAS that already runs DockerDocker with Compose

All three keep your data in one folder, ~/.open-net-worth/, outside the app itself. Updating or reinstalling the app never touches it. There is no account to create and no .env file to write.

Supported platforms

PlatformDesktop appServer (onw)Docker
macOSApple Silicon only (signed and notarized)YesYes
Windows 10/11x64Yes (see the Windows note)Yes
Linuxx86_64, AppImage or .debYesYes

Intel Macs and arm64 Linux have no desktop build yet — use the server or Docker there.

The desktop app bundles its own Python, the web interface and this help. You don’t install Python, Node or Docker.

macOS (Apple Silicon)

  1. Go to opennetworth.ai/download/mac and download the DMG.
  2. Open it and drag Open Net Worth into Applications.
  3. Open it from Applications.

Or install from Terminal (it checks the download’s checksum before installing):

Terminal window
curl -fsSL https://opennetworth.ai/install.sh | sh

Windows 10/11 (x64)

  1. Go to opennetworth.ai/download/windows and run the installer. It installs for your user only — no administrator prompt.
  2. The installer is not code-signed yet, so Windows SmartScreen may warn you. Click More info → Run anyway.

Or in PowerShell (checks the download against the release’s SHA256SUMS first):

Terminal window
irm https://opennetworth.ai/install.ps1 | iex

To refuse any installer without a valid signature, add -RequireSigned, or set $env:ONW_REQUIRE_SIGNED = '1' before piping to iex.

Linux (x86_64)

Pick one:

  • Terminal: curl -fsSL https://opennetworth.ai/install.sh | sh — installs the AppImage to ~/.local/bin/open-net-worth with a launcher entry, no sudo, after checking its checksum.
  • AppImage: download it from opennetworth.ai/download/linux, run chmod +x on it, then run it.
  • .deb: download Open-Net-Worth-linux-amd64.deb from the releases page, then sudo apt install ./Open-Net-Worth-linux-amd64.deb.

After installing

On first launch, click Get started, then choose where your book lives (Continue keeps the suggested folder; On your own server connects to a server you already run). Then follow Your first run.

To upgrade, the app updates itself (see Desktop app § Updates), or re-run the terminal installer. To remove the app on macOS or Linux: curl -fsSL https://opennetworth.ai/install.sh | sh -s -- --uninstall. Your book is never removed.

Option B: run it as a server

The server is the same app as one process that serves both the API and the web interface on port 8080. You open it in a browser, or connect the desktop app to it from another computer.

macOS and Linux

  1. Open a terminal and run the installer:

    Terminal window
    curl -fsSL https://github.com/open-net-worth-ai/open-net-worth-releases/releases/latest/download/install-server.sh | sh

    It installs uv if you don’t have it, then installs open-net-worth on uv’s own Python 3.12. You need no system Python or Node.js. The first install downloads a few hundred MB. It also adds ~/.local/bin to your shell’s PATH if it isn’t there yet. The terminal you ran it in can’t see that change, so the installer then shows the source line that reloads it, naming the file it changed: source ~/.zshenv for zsh, source ~/.bashrc for bash. Opening a new terminal works too. It finishes by listing the commands you’re likely to need next.

  2. Start it and open it in your browser:

    Terminal window
    onw start --open

  3. Your browser opens http://127.0.0.1:8080. Follow Your first run.

Add --autostart to the end of the installer command (… | sh -s -- --autostart) to also start it at login and restart it if it crashes. Add --auto-upgrade instead to do that and also install new versions automatically — see Upgrading.

Windows

The install-server.sh script is for macOS and Linux. On Windows, in PowerShell:

  1. Install uv: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  2. Open a new PowerShell window and run uv tool install --python 3.12 open-net-worth
  3. Run onw start --open

The onw command

CommandWhat it does
onw startRun the app. --open opens your browser once it’s up; --port 9000 or --host 0.0.0.0 override the defaults (127.0.0.1:8080). It stays in that terminal until you press Ctrl+C. --background frees the terminal and keeps it running until onw stop or a reboot; --autostart runs it as the boot service, which also starts it at login and restarts it after a crash; --auto-upgrade installs new versions automatically (Upgrading).
onw stopStop it, however you started it, once any save or import in progress has finished (it waits up to a minute). A reply Lucius is writing is cut off, as with Ctrl+C. If it runs as the boot service, this tells you to use onw autostart uninstall, because the service would only start it again.
onw restartRestart it the way it was running: in its terminal, in the background or as the boot service. It waits for a save or import in progress, as onw stop does, and says when it’s back.
onw statusShow whether it’s running, its URL and version, the working folder, the boot service, where the log is, and how an upgrade is going or why it failed. If it isn’t running, it says so and exits with an error code, so scripts can check it too. It looks at the server for this working folder on this machine. For Docker, use docker compose ps.
onw logsShow the end of its log. --follow (-f) keeps showing what’s added until you press Ctrl+C; --lines 200 (-n) shows more.
onw autostart onTurn autostart on: the app starts now, by itself at every login, and again after a crash. It uses a launchd agent on macOS, a systemd user service on Linux, and a Task Scheduler task on Windows, with no sudo or admin. The same as onw start --autostart.
onw autostart offTurn it off: the app stops and won’t start by itself again. Your book isn’t touched.
onw autostartSay whether it’s on, and whether auto-upgrade is on. onw autostart status does the same. The older names install, uninstall and stop still work.
onw upgradeUpdate to the newest release. A running server installs it and restarts once it’s idle (Upgrading). --check only says whether one is out.
onw reset-passwordSet a new password if you’ve forgotten it — see I lost my password.
onw mcpLet another AI app (Claude Desktop, Cursor…) use your book — see Connect AI apps.
onw versionPrint the installed version.
onw helpList the commands. onw help start shows one command’s options, the same as onw start --help.

Every command exits with 0 when it worked, 1 when it didn’t (for onw status, when the app isn’t running), 2 when the command was typed wrong, and 130 when you press Ctrl+C. Scripts can rely on that.

On macOS and Linux, onw autostart logs go to ~/.open-net-worth/logs/.

To use this server from the desktop app on another computer, choose On your own server at setup — see Desktop app § Connect to a server. Before you open it from another device, read A note on network access.

Option C: Docker

  1. Download the Compose file into an empty folder:

    Terminal window
    curl -fsSLO https://github.com/open-net-worth-ai/open-net-worth-releases/releases/latest/download/docker-compose.yml

  2. Pick a password (at least 8 characters) and start it:

    Terminal window
    AUTH_PASSWORD='pick a password' docker compose up -d

    In Windows PowerShell, use curl.exe in step 1, and for step 2: $env:AUTH_PASSWORD='pick a password'; docker compose up -d.

  3. Open http://localhost:8080 and sign in with that password. First run continues from there.

The password is required under Docker — Compose refuses to start without it. Docker’s networking hides the fact that your browser is on the same machine, so without a password nothing could ever operate the app. Your first run § Docker explains this and what to do if you started without one.

To make the password stick, put AUTH_PASSWORD=... in a .env file next to docker-compose.yml; Compose reads it on every up. It only sets the password the first time — change it later in Settings → Security.

What the Compose file does:

  • Pulls ghcr.io/open-net-worth-ai/open-net-worth, pinned to the release the file came with (set ONW_VERSION=x.y.z to run another one). The image also has latest and 0.1 tags that move to each new release — see Upgrading.
  • Publishes port 8080 on 127.0.0.1 only, so other devices on your network can’t reach it until you change that line (the comment beside it explains the risk). PORT=9000 picks another port.
  • Keeps your data in a Docker volume named open-net-worth-data, which survives docker compose down (only docker compose down -v deletes it).
  • Restarts the app after a crash or reboot (restart: unless-stopped).

To update, download the new Compose file and run docker compose pull && docker compose up -d — see Upgrading. To use a Claude or ChatGPT subscription from inside the container, see Connecting an AI provider.

From source (developers)

For people working on the code. In a checkout of the source, with Python 3.12+ and Node.js 22+ installed (macOS or Linux):

Terminal window
make setup start

make setup creates .venv, installs dependencies and the onw command, builds the web interface and this help, and migrates the database. make start runs it on http://127.0.0.1:8080. make autostart runs setup, then onw autostart on. CONTRIBUTING.md covers the two-process dev mode (uvicorn --reload + npm run dev) and the test gate.

make seed fills an empty book with a fabricated example — about two and a half years of accounts, transactions, holdings and a budget — so you can look around first. It refuses to run on a book that already holds data.

A note on network access

On the machine running Open Net Worth, you’re trusted without a password — any browser or program on that machine (localhost) can use it. That’s deliberate for a single-person app.

A password matters once you open it from anywhere else: another device on your network, a reverse proxy, or Docker (whose networking hides that you’re on the same machine).

Until a password is set, the server only opens on its own machine, so nobody else on the network can claim it first. Opening it from another device shows Set a password first: go to the computer it runs on, set one in Settings → Security, then click I’ve set it, sign in.

Forgot it? See I lost my password. Exposing it beyond your own machine is covered in Exposing it beyond localhost.

Troubleshooting

  • onw: command not found after installing — ~/.local/bin isn’t on your PATH yet. Open a new terminal, or run uv tool update-shell and then open a new terminal.
  • AUTH_PASSWORD is required for a Docker install — Compose stopped on purpose. Run the up command with AUTH_PASSWORD=... in front, or add it to a .env file.
  • Port 8080 is already in use — start on another port: onw start --port 9000, or PORT=9000 docker compose up -d.
  • The app won’t start — see The backend won’t start.

Guides and comparisons

Longer write-ups on the Open Net Worth blog: