Environment variables

You don’t need any of these for a normal install. make setup start, onw start and the desktop app all run with no configuration. The one exception is Docker, which requires AUTH_PASSWORD (see Auth).

Your AI provider and model, your password, and every connector (email, Telegram, banks, search) are set up inside the app — Settings and the Connectors screen. They are not read from environment variables. The exceptions are AUTH_PASSWORD under Docker and the AI key fallback described below.

How to set one

Running from a checkout (make start / uvicorn): copy .env.example to .env in the repository folder and uncomment the lines you need. The file is read at startup. Restart the app after a change.
onw start (installed with uv tool): set the variable in your shell, e.g. PORT=8081 onw start. If you use onw autostart install, the boot service carries over HOST, PORT, ONW_ROOT, DATA_DIR, CACHE_DIR and LOGS_DIR from the shell you ran it in — run it again after changing them.
Docker: put NAME=value lines in a .env file next to docker-compose.yml, or pass them on the command line: AUTH_PASSWORD=… docker compose up -d.
Desktop app: it ignores .env and sets up its own server. The only variable meant for it is ONW_DESKTOP_UPDATES=0, which stops it checking for updates (see Desktop app only).

Where things live

Variable	Default	What it does
`ONW_ROOT`	`~/.open-net-worth`	The one to use. The working folder that holds `data/`, `cache/`, `logs/` and `backups/`. Point it at another drive, a NAS mount, or a second instance’s folder. It overrides the four below.
`DATA_DIR`	`<ONW_ROOT>/data`	Older per-folder override for the database and your files. Prefer `ONW_ROOT`.
`CACHE_DIR`	`<ONW_ROOT>/cache`	Price and rate caches — safe to delete.
`LOGS_DIR`	`<ONW_ROOT>/logs`	The app log.
`BACKUPS_DIR`	`<ONW_ROOT>/backups`	Daily backups.
`ONW_DATABASE_URL`	`sqlite:///<DATA_DIR>/onw.db`	Use Postgres instead of the built-in SQLite file, e.g. `postgresql+psycopg://user:pass@host/db`. See SQL console and Postgres.

Two instances can’t share one working folder — the second refuses to start (see The backend won’t start). Give each its own ONW_ROOT. The full layout is in Where your files live.

Server

Variable	Default	What it does
`HOST`	`127.0.0.1`	The address to listen on. `0.0.0.0` makes the app reachable from other devices on your network — read Exposing this beyond localhost first. Docker sets this for you.
`PORT`	`8080`	The port the app listens on.
`CORS_ORIGINS`	`http://localhost:5174,http://localhost:8080`	Comma-separated web addresses allowed to call the API from a browser. `*` allows any — don’t, on anything reachable from a network.
`ONW_ALLOWED_HOSTS`	unset	Extra hostnames (comma-separated, no port) you use to reach the app from this machine — for example a name you put in your hosts file. `localhost`, `127.0.0.1`, `[::1]` and the hostnames in `CORS_ORIGINS` always work; any other name gets a 421 `host not allowed` error until you add it here.

Auth (instance password)

The password is normally set from the app on first run and changed in Settings → Security.

Variable	Default	What it does
`AUTH_PASSWORD`	unset	A password to store on first boot, when none is stored yet. Required for Docker — Compose refuses to start without it. Ignored once a password is stored, so it is not a way to reset one — use `onw reset-password`. The app logs a reminder to remove it after it has been used.
`AUTH_PASSWORD_HASH`	unset	The same, but already hashed (`pbkdf2$…`). Preferred over `AUTH_PASSWORD` in scripts, so the plain password never sits in a file.
`AUTH_TRUST_LOOPBACK`	`true`	By default, a browser on the same machine is let in without the login screen. `false` requires the password even there.
`AUTH_DISABLED`	`false`	`true` turns the login off entirely. For development only — never on an instance anyone else can reach.
`AUTH_API_TOKEN`	generated	The bearer token for scripts and API access. Normally generated and shown in the app.
`AUTH_SESSION_KEY`	generated	The key that signs login sessions. Changing it signs everyone out.
`AUTH_SESSION_TTL`	`2592000` (30 days)	How long a login lasts, in seconds.

Running behind an authenticating proxy (gateway mode)

Variable	Default	What it does
`ONW_GATEWAY_TOKEN`	unset	A shared secret, at least 32 characters, for running behind a proxy that does the sign-in for you. Shorter, and the app refuses to start with `ONW_GATEWAY_TOKEN must be at least 32 characters`.

When it’s set, every request must carry the value in an X-Onw-Gateway-Token header or it gets a 403 (only GET /api/health is exempt). Setup steps: Running behind an authenticating proxy.

Optional features

Variable	Default	What it does
`ONW_TERMINAL_ENABLED`	`false`	Turns on Settings → Terminal, a shell on this machine in your browser. Needs a password set. Always on behind a gateway. See Terminal.
`ONW_ALLOW_PRIVATE_ENDPOINTS`	`1`	Lets an AI provider address, webhook or MCP server point at your own machine or local network (a local Ollama or LiteLLM, for example). `0` blocks those. Always blocked in gateway mode.
`ONW_REPORTS_URL`	`https://cloud.opennetworth.ai/api/problem-reports`	Where Report a problem sends a report, only when you press Send. Must be `https` (plain `http` only for a loopback address). The desktop app reads it too. See Reporting a problem.
`ONW_TURN_TIMEOUT_S`	`1200`	The default limit, in seconds, on how long one Lucius reply may run. Settings → AI → Turn time limit overrides it.
`SSL_CERT_FILE` / `SSL_CERT_DIR`	unset	Standard variables for a custom certificate bundle — for a network that inspects HTTPS with its own certificate.

AI provider

Choose the provider and model in Settings → AI Model; AI_PROVIDER, AI_MODEL and OPENAI_BASE_URL are not read. Two variables remain:

ANTHROPIC_API_KEY / OPENAI_API_KEY — used only while no key is saved in Settings (a QA copy or a hosted demo supplies its key this way).
AI_MEMORY_MODEL — a cheaper model for background memory extraction.

ONW_DISABLE_TELEGRAM=1 skips the Telegram connector entirely.

Desktop app only

Variable	What it does
`ONW_DESKTOP_UPDATES`	`0` stops the desktop app checking `opennetworth.ai` for updates (every 4 hours). Set it in the environment the app is launched from.
`ONW_REPORTS_URL`	Also read by the desktop app — see Optional features.

Docker only

Variable	What it does
`ONW_VERSION`	Which published image `docker-compose.yml` runs, e.g. `ONW_VERSION=0.2.1 docker compose up -d`. Defaults to the release the compose file shipped with.

Public demo only

For hosting a public demo of made-up data — never on a real book. DEMO_MODE=true locks the instance down and meters AI use per visitor; DEMO_OPEN_ACCESS=true (only together with DEMO_MODE) lets visitors in without a password; DEMO_TRUSTED_PROXY_HOPS is the number of proxies in front that add to X-Forwarded-For (default 0). The per-visitor limits are DEMO_TURNS_PER_WINDOW (30), DEMO_TURN_WINDOW_S (300), DEMO_TOKENS_PER_IP_DAILY (3,000,000) and DEMO_TOKENS_TOTAL_DAILY (30,000,000).

Not for you to set

ONW_QA_MODE, ONW_QA_NONCE and the ONW_EVAL_* / ONW_BUILDER_ROOT variables are for the project’s own automated tests. ONW_QA_MODE=1 makes the app refuse to start against your real data folder.
ONW_DESKTOP_MODE and ONW_DESKTOP_INSTANCE_ID are set by the desktop app for its own server.
ONW_BASE_URL / ONW_API_TOKEN are read only by the onw mcp bridge that another AI app starts — see Connect AI apps.
The ONW_CLAUDE_CLI_*, ONW_CODEX_*, CODEX_HOME, CLAUDE_CONFIG_DIR, ONW_FULL_TOOL_OFFER, ONW_READ_CACHE and ONW_MIGRATE_ASSUME_BACKUP variables are internal tuning and debugging switches. Leave them alone unless a maintainer asks you to set one.