Connecting an AI provider

Lucius needs an AI model to think with. You connect one during first run (Step 2, Connect Lucius), and can add or change it any time in Settings → AI.

Open Net Worth itself is free; you pay your model provider, or nothing at all with a local model. There are three kinds of connection:

Option	You need	Cost
A subscription you already pay for — Claude Code or Codex	A Claude or ChatGPT plan that includes it	Included in your plan; plan limits apply
An API key — OpenRouter, Anthropic, OpenAI, Gemini, xAI, Zhipu	An account with that provider	Pay per use, billed by the provider
A local model — Ollama, LM Studio, LiteLLM	A model running on your own computer	Free, but needs a capable machine

Lucius works through long chains of tool calls, so a strong model matters. If you’re unsure, start with a subscription you already have, or OpenRouter (one key, many models, including cheaper capable ones).

Use a Claude or ChatGPT subscription

No API key needed. The app runs the official command-line tool (Claude Code for Claude, Codex for ChatGPT) on the same computer, signed in to your account.

Install it on the computer running Open Net Worth. With the desktop app, that’s your computer. With a server, it’s the server — which may not be the device showing the browser.

In first run’s Connect Lucius step, or in Settings → AI under Connect a subscription, find Claude Code or Codex and expand Install & sign in.

Copy step 1, the install command (it matches the server’s operating system), and run it in Terminal (macOS/Linux) or PowerShell (Windows):

	macOS / Linux	Windows (PowerShell)
Claude Code	`curl -fsSL https://claude.ai/install.sh \| bash`	`irm https://claude.ai/install.ps1 \| iex`
Codex	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`	`powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"`

Open a new terminal and run step 2, the sign-in command:
- Claude Code: claude auth login, then choose your Claude subscription.
- Codex: codex login, then choose Sign in with ChatGPT.
Go back to the app. It checks every few seconds, so the row changes to Found Claude Code on this machine (or Codex) on its own. Click Use this.
The Model is preset to whatever that tool already runs by default. Click Continue.

In Settings, a found tool appears in AI providers with an Installed badge; choose one of its models under Default model to make Lucius use it.

Other install methods are in the official Claude Code setup and Codex instructions.

Google Antigravity: if Google’s Antigravity CLI (agy) is installed and signed in on that computer, it’s offered as Antigravity CLI the same way.

Installed somewhere unusual? In Settings → AI, click Edit on the provider and set Binary path to the full path of claude or codex. The macOS desktop app already looks in ~/.local/bin, /opt/homebrew/bin and /usr/local/bin.

When the tool updates itself: Claude Code and Codex update on their own. The first time Open Net Worth starts with a new version, it quietly checks that Lucius’s tools still work through it. If an update broke that, a notification in the bell says so; switch model in Settings → AI, or update Open Net Worth.

Subscription on a remote server

Install and sign in on the server itself, over SSH. If the server’s administrator has turned on the in-app terminal, you can do it from Settings → Terminal instead — see Terminal.

Subscription under Docker

The Docker image already includes Claude Code and Codex, so Settings → AI lists them with a path like /usr/local/bin/codex. That path is inside the container, not on your computer or NAS. The container has its own filesystem, so these tools start signed out, and they can’t see a sign-in, an Ollama or any other AI tool on the machine around them.

The row says Not signed in until you sign in. Run the command for your tool on the machine hosting the container, using your own container name if you changed it from open-net-worth:

docker exec -it open-net-worth codex login --device-auth

docker exec -it open-net-worth claude auth login

Follow the link it prints, on any device. The row changes to Signed in by itself, and Lucius uses the sign-in on your next message.

With the current docker-compose.yml, the sign-in stays in its own Docker volume (open-net-worth-codex, open-net-worth-claude), so updates keep it. With an older file or a plain docker run, it is lost whenever the container is recreated: download the new file, or mount your own volumes at /home/onw/.codex and /home/onw/.claude. These volumes hold your sign-in and aren’t part of the app’s backups.

Or share a sign-in from the host:

On the host (not in the container), sign in first:
- Claude Code: run claude setup-token. This is needed even if claude already works for you — macOS keeps the sign-in in the Keychain, which the container can’t read.
- Codex: codex login is enough.
In docker-compose.yml, uncomment the matching line under volumes: (~/.claude/.credentials.json or ~/.codex/auth.json). Do this after step 1 — mounting a file that doesn’t exist yet creates an empty folder instead. The container runs as user ID 1000, so that user must be able to read the file. A file created by root usually can’t be read, and the row shows Not signed in.
Run docker compose up -d again.

Use an API key

Get a key from the provider (table below). Most providers need a payment method or prepaid credit before the key works.
In first run: below or use a provider, pick the Provider, paste the key into API key, and click Continue. The app checks the key with the provider and loads its model list — if the provider refuses the key, you can’t go on until you fix it. Then pick the Model and click Continue.
In Settings → AI: click ＋ Add provider, pick the Provider, paste the API key, choose a Default model, and click Add provider. To make Lucius use it, pick one of its models under Default model.

Provider (as listed in the app)	Where to get a key
OpenRouter	openrouter.ai → sign in → Keys → Create key. Add credits under Credits. One key reaches models from many companies. Pick a model on par with Claude Sonnet, such as GLM or Kimi — weaker models slip on long tasks.
Anthropic	console.anthropic.com → API keys → Create key. Add credit under Billing. Keys start with `sk-ant-`. On a Claude Max or Team plan, claim the plan’s monthly API credits first: on claude.ai, Settings → Billing → API credits → Link organization, then create the key in that Console organization. Credits expire at the end of each billing cycle. Pro includes none.
OpenAI	platform.openai.com → API keys → Create new secret key. Add credit under Billing.
Google Gemini	aistudio.google.com → Get API key → Create API key.
xAI (Grok)	console.x.ai → API keys → create a key.
Zhipu (GLM)	z.ai → API keys. The endpoint can be changed if you use the mainland China service.
Custom (OpenAI-compatible)	Any service that speaks the OpenAI API (DeepSeek, Moonshot, a self-hosted gateway). Enter its Endpoint URL and key. Add it as many times as you like — give each a Display name and they sit side by side.

The key is stored on the machine running Open Net Worth only. It’s never sent to Lucius, never included in an export, and the field hides it (you can reveal it in Settings to check it).

Use a local model

Free, and nothing leaves your machine — but you need a computer that can run a capable model with tool calling. Small models often struggle with Lucius’s longer tasks.

Ollama

Install Ollama from ollama.com and start it.
Download a model, for example ollama pull <model-name> in a terminal.
In the app, pick Ollama (local). The Endpoint is preset to http://localhost:11434/v1. Click Continue, then pick your model.

Running Open Net Worth in Docker? localhost then means the container, not the machine running Ollama. Make Ollama listen on your network by setting OLLAMA_HOST=0.0.0.0 where it starts, then use that machine’s network address as the Endpoint, such as http://192.168.1.20:11434/v1. Ollama has no password, so every device on your network can use it after this.

LM Studio — start LM Studio’s local server, then pick Custom (OpenAI-compatible) with the endpoint http://localhost:1234/v1. LM Studio doesn’t check keys, so any text works in API key.

LiteLLM Proxy (local) — for your own LiteLLM gateway. The endpoint is preset to http://localhost:4000; the key is optional (only if your proxy was started with one).

“Local” means local to the machine running Open Net Worth. A model on your laptop isn’t reachable from a server elsewhere.

Check that it works

Open the Lucius chat and ask something like:

What’s my net worth?

A real answer means you’re connected. In Settings → AI, you can also click Edit on a provider, then Test connection.

What it costs

Open Net Worth charges nothing. A subscription uses your plan’s limits; an API key is billed by the provider per use. There’s no single honest number — it depends on the model and how much you use Lucius.

To see and control it:

Settings → Cost & Performance → AI spend shows what you’ve spent — today, yesterday, the last 7 or 30 days, or all time — with a timeline, a breakdown by surface, provider and model, and a projected monthly cost.
Settings → AI → Task models runs background chores (like automations) on a cheaper model; chat keeps your default.
Settings → Chat has switches for extras that use tokens, such as follow-up suggestions and memory, and Show cost per turn to see each reply’s cost in the chat.

Without a model

First run asks for a model — there’s no skip. If you don’t want to pay, use a free local model. If your model later becomes unavailable (out of credit, signed out), everything except Lucius keeps working: accounts, the ledger, budgeting, investments and CSV/OFX/QIF import. What needs a model: chatting with Lucius, reading PDF statements and screenshots, auto-categorizing, automations and memory.

Troubleshooting

“That key was rejected by …” — the provider refused the key. Copy it again with no spaces at either end, and check the key hasn’t been revoked.
“Could not reach …” — the app couldn’t get an answer from the provider. Check your internet connection, that you’ve added credit to the account, and — for a local model — that Ollama or LM Studio is running and the endpoint is right.
Claude Code or Codex stays “Not installed” — install it on the computer running Open Net Worth, then open a new terminal so it’s on your PATH. Still not found? Set its Binary path in Settings → AI.
“Not signed in” or “isn’t signed in where Open Net Worth runs” — the tool is there but has no sign-in Lucius can use. Run claude auth login or codex login on the computer running Open Net Worth. On a server you reach over SSH, use codex login --device-auth. Under Docker, see Subscription under Docker. The row in Settings → AI gives the exact command. If the row says Signed in but Lucius still refuses, the sign-in has expired: run the same command again.
“Choose a default model on another provider first” — you tried to switch off the provider Lucius uses by default. Pick another Default model first.

Guides and comparisons

Longer write-ups on the Open Net Worth blog:

An Open-Source Claude Personal Finance Alternative: using a Claude subscription with your own ledger
Private AI financial assistant: where your data goes: what each model choice means for your data