<div align="center"> <img src="assets/icon.svg" width="76" alt="openportfolio" />

openportfolio

Every account as one book. Every call on the record.

Open-source, self-hosted portfolio tracker. It pulls every brokerage, pension, wallet and bank account into a single net worth, stores the investor flows behind the price, and Brier-scores the forecasts you registered before the fact. No provider API key, anywhere in it.

Website · Docs · Live demo

_{Dashboard and backend in one click. The sync worker runs on your machine, by design: see Deploying.}

</div> <img src="assets/demo.gif" alt="A walk through the openportfolio demo: the net worth view with its breakdowns by venue and asset class, then flows by investor type, then the track record with its mean Brier score and reliability table, then the decisions queue" />

_{The recording and the screenshots show the demo book. Every figure in them is invented.}

Status: pre-release. It runs and the setup below works. Interfaces will still move.

It is not a trading bot. The backend has no function that places an order, the adapters that ship declare canPlaceOrders: false, and PlaceOrderRequest requires an OrderConfirmation that has no default. What it does is aggregate, watch, and keep score.

Nor is it an AI analyst. Plenty of tools will now have a model read the market and hand you a view. What openportfolio adds is the part they leave out: every call, a model's or your own, is registered with a probability and a horizon before the fact and Brier-scored after it, so a fluent analyst and an accurate one stop looking the same.

Why

Two problems that look unrelated and are the same problem.

A portfolio is scattered by construction. A broker here, a pension there, an ISA, an exchange account, a bank balance, a holding that no API will ever return. Every one of those apps shows you a number, and none of them shows you yours. So the figures that actually decide things, the total, the concentration in one name, the share of the book sitting in a currency you do not spend, are the figures nobody has. They get estimated, and the estimate is generous in the direction that avoids a decision.

Market commentary is unaccountable, and became more so the moment a model would produce a confident directional view on anything you asked it. The problem is not that the views are wrong. It is that being wrong costs nothing and leaves no trace, so a forecaster worth reading and a forecaster who is merely fluent are indistinguishable from the outside, and from the inside too.

Both are bookkeeping failures, so openportfolio treats them as bookkeeping.

| | | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | One net worth | Accounts pulled through venue adapters into a single base currency, with the rate stored on the row it converted, so a snapshot records what the book was worth then rather than what today's rates say. Positions held in three places are one exposure. | | Flows, not just prices | Price is the output of who was buying and who was made to sell. Net buying by investor type, turnover, and a calendar of dated forward events are stored as first-class series, not derived when somebody remembers to ask. A forced seller is on a schedule, and the schedule is public. Positioning by participant class arrives keyless from the CFTC's weekly Commitments of Traders. | | A scored track record | A call is registered before the fact with a probability, a horizon and the condition that settles it. When the horizon passes, the machine-resolvable ones settle themselves and are Brier-scored. The reliability diagram is the product: it shows what you said, what happened, and the gap between them. |

There is a fourth table that exists for one reason. A recommendation phrased as "wait for the print, then decide" evaporates the moment it is said out loud. decisions is a queue of those, each with a trigger condition and an outcome, and they stay on the board until one of them changes.

<table> <tr> <td width="50%"><img src="assets/screenshots/track-record.png" alt="Track record view: mean Brier score over scored calls, with a reliability table comparing what was said against what happened" /></td> <td width="50%"><img src="assets/screenshots/flows.png" alt="Flows view: net buying by investor type over thirty sessions, with turnover on every row" /></td> </tr> <tr> <td align="center">_{<b>Track record.</b> Said versus happened, bucket by bucket.}</td> <td align="center">_{<b>Flows.</b> Net buying by investor type, turnover on the same row.}</td> </tr> </table>

No provider API key

Watching a book is only useful if something is actually watching: reconciling after the close, settling a call the day its horizon passes, noticing that a deferred decision came due three weeks ago.

Metered inference is the wrong shape for that. When each run bills per token, every autonomous check becomes a purchase, and a product that spends the operator's money unprompted has to ask first, or batch, or ration. All three turn a portfolio that watches itself into a portfolio that asks permission to look.

So every model call is dispatched instead to an agent CLI you are already signed in to: codex, antigravity, or claude, with a per-task fallback order. There is no provider key in this repo and no field to put one in. That does not make a run free: subscription plans have rate limits, and the fallback chain exists partly because one provider runs out before the others do. What changes is the kind of limit. Agent work is bounded by quota and wall clock rather than by spend, so it never has to be justified one invocation at a time.

The consequence is that openportfolio is self-hosted by design. Your deployment runs your syncs on your machine under your own logins, against your own accounts.

What it does

| Surface | | | ------------- | --------------------------------------------------------------------------------------------------------------------- | | Net worth | accounts, balances, per-venue and per-asset-class breakdown, snapshots in one base currency, keyless FX | | Venues | adapter contract with declared capabilities; keyless quote adapters for listed instruments and for coins, plus a manual one | | Flows | net buying and turnover by investor type per session, per market or per symbol | | Forecasts | probability, horizon and resolution criterion; auto-resolution on horizon expiry; Brier score and reliability buckets | | Decisions | the deferred-decision queue, with trigger conditions and outcomes | | Catalysts | dated forward events and the assets they touch | | Audit | append-only record of every state-changing mutation, including what the cron did unattended | | MCP | 25 tools so codex / antigravity / claude can read and write the book directly | | Notifications | optional Telegram messages from the workers: calls settled, decisions come due. The token stays in the worker process | | Multi-tenancy | every table scoped to a tenant, every index leading with it, one service key per tenant |

Quick start

With Docker

Nothing but Docker, and no Convex account: the backend is Convex's own self-hosted image, running on your machine.

git clone https://github.com/seonglae/openportfolio.git
cd openportfolio
docker compose up -d        # http://127.0.0.1:6101

That starts the backend, pushes the functions to it, creates a book called home in GBP (OPENPORTFOLIO_DEV_TENANT and OPENPORTFOLIO_BASE_CURRENCY change both), then serves the dashboard and runs the sync worker. The Convex dashboard is on 127.0.0.1:6791; it asks for an admin key, which docker compose exec backend ./generate_admin_key.sh prints. docker compose down stops it and keeps the data; down -v deletes the book.

Every port is published on 127.0.0.1 only, because sign-in is off in this mode and the dev tenant answers anyone who reaches the backend. Read Before exposing it before changing that. The agent worker is not in the compose file: it dispatches to an agent CLI you are signed in to, and a container has none. Run it on the host against the same backend.

To drive the book from the host, point the Convex CLI at the container:

export CONVEX_SELF_HOSTED_URL=http://127.0.0.1:3210
export CONVEX_SELF_HOSTED_ADMIN_KEY="$(docker compose exec -T backend ./generate_admin_key.sh)"
npx convex run accounts:link '{"accountKey":"isa","venue":"manual","kind":"brokerage","label":"ISA","currency":"GBP"}'

With a Convex account

Node 22+, pnpm, and a Convex account. The free tier is enough.

git clone https://github.com/seonglae/openportfolio.git
cd openportfolio
pnpm install

cp .env.example .env.local
npx convex dev --once          # creates the deployment

# create the first book
npx convex env set OPENPORTFOLIO_DEV_TENANT home
npx convex run tenants:create '{"slug":"home","name":"Home","baseCurrency":"GBP"}'

# the UI, then the sync loop
pnpm --filter openportfolio-browser dev   # http://localhost:6101
npx tsx sync-worker.mts --once

With nothing linked it registers the venues it can serve and records a net worth of zero, which is correct. Add a manual holdings file to get a real one:

[
  { "accountKey": "isa", "symbol": "VWRL", "assetClass": "etf", "qty": 40, "price": 118.2, "currency": "GBP" },
  { "accountKey": "wallet", "symbol": "BTC", "assetClass": "crypto", "qty": 0.15, "price": 0, "currency": "USD" }
]

export OPENPORTFOLIO_MANUAL_HOLDINGS=$