Files
brokeless/README.md
T
MangaValkandClaude Opus 5.5 dee883472a MCP: the add command uses --scope user
Without it Claude Code keeps the server for the one folder the command ran in,
so sessions elsewhere don't see brokeless.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 21:13:02 +01:00

225 lines
13 KiB
Markdown

# brokeless
See where your money goes, get a plan for it, and ask a local AI about it. Everything runs on your own server: the app, the database, sign-in and the AI. Nothing goes to the cloud.
brokeless is a self-hosted copy of [broke](https://github.com/nextwork-projects/broke) by NextWork (MIT). It keeps broke's features and adds a complete Docker setup, Dutch bank import and a few fixes. New broke changes are reviewed by hand before they come in.
## What's different from broke
| | broke | brokeless |
| --- | --- | --- |
| Database and sign-in | Supabase cloud project | Supabase's own Postgres, Auth and REST images, in Docker on your server |
| Sign-in emails | Supabase sends them | Mailpit catches them on your server, or your own mail server |
| Hosting | Your computer, or Vercel | Docker, for example on Unraid |
| AI | Your Claude/Codex/Gemini login, OpenRouter, or a local model | Ollama in the same Docker setup (the others still work if you want them) |
| Banks | Plaid and other cloud bank feeds | Statement import (CSV, OFX, QIF, PDF), or link ING and other European banks through Enable Banking (optional, goes through their cloud) |
| Enable Banking feed | Never run against the real service | Checked against their API docs; fixes for duplicate transactions and pasted keys; tested end to end against a stand-in |
| ING Netherlands CSV | Spending and income all came in as income | Reads the "Af Bij" column |
| ABN AMRO TXT/TAB | Imported nothing (no header row) and kept coded descriptions | Recognized, with the name pulled out of `/NAME/`, card and `Naam:` text |
| Updates | Pulls from GitHub on every start | Never by itself. You review upstream commits and merge the ones you want. |
| Charts | Month bars and a category breakdown | A Charts tab under Spending: cash flow, savings rate, categories over time, this month vs last, balance over time, top merchants, spending by weekday and biggest changes, with filters and compare |
| Calls out | Update check on GitHub, exchange rates from frankfurter.dev | Both off (`BROKE_OFFLINE=1`) |
| Next.js and React | 15.5.4 and 19.1.0 (critical advisory) | 15.5.29 and 19.1.10 |
Also fixed: sign-in links sent you to `http://0.0.0.0:3000` behind Docker or a proxy. Redirects now use the address your browser used.
## Run it
Needs Docker with Compose. The steps below use Unraid's IP as the example, but any Linux server works.
1. Get the code on your server:
```bash
git clone https://mangavalk.com/mangavalk/brokeless.git
```
2. Make the secrets. Use the address you'll open brokeless on, with your server's LAN IP or name (not `localhost`: the containers need to reach it too):
```bash
cd brokeless && node docker/setup.mjs --url http://192.168.1.10:3003
```
No Node on the server:
```bash
docker run --rm -v "$PWD":/w -w /w node:22-alpine node docker/setup.mjs --url http://192.168.1.10:3003
```
This writes `docker/.env` with a new database password, signing keys and a Mailpit password. On Unraid, set `DATA_DIR=/mnt/user/appdata/brokeless` in it.
3. Start it, with local AI:
```bash
docker compose -f docker/docker-compose.yml --profile ai up -d --build
```
Then pull a model for Ollama (pick one that fits your RAM or GPU):
```bash
docker exec brokeless-ollama-1 ollama pull qwen3:8b
```
Leave out `--profile ai` to run without AI.
4. Open `http://192.168.1.10:3003` and type your email. Open Mailpit on port 8025 (user `broke`, password `MAIL_PASSWORD` from `docker/.env`) and click the sign-in link.
5. Lock it to you: set `DISABLE_SIGNUP=true` in `docker/.env`, then run the `up -d` command again.
6. Add your bank: Accounts, Add accounts, Import a statement. For ING, download your transactions from Mijn ING as CSV (comma or semicolon both work). For ABN AMRO, download them as TXT (a `.TAB` file). Importing the same file again adds nothing. To have transactions come in by themselves instead, see [Link your bank](#link-your-bank-ing-and-other-european-banks).
More detail, including what each container does: [docker/README.md](docker/README.md).
## Link your bank (ING and other European banks)
Optional. Instead of importing exports, brokeless can read your transactions straight from ING (and most banks in the UK and EU) through [Enable Banking](https://enablebanking.com), a licensed open-banking service. It can only read, never move money.
Know before you start:
- **It isn't fully local.** Your transactions pass through Enable Banking's servers on their way to your database.
- **Restricted mode is for your own accounts.** Enable Banking calls it "individual non-commercial use". Their docs don't list a price; check their site.
- **Access runs out.** ING lets it last up to 180 days. Two weeks before, Accounts warns you; after, it says "Needs attention". Press **Link again** and approve at the bank: your accounts, history and edits stay, nothing is added twice.
- **Usually only payment accounts.** Banks must share payment accounts. Dutch banks often leave savings out, and investment accounts are never included. Keep importing statements for those.
- **A linked account and a CSV account are two accounts.** Where both cover the same days, those transactions count twice. Fix it in one step: Accounts, edit the CSV account, **Merge into a linked account**. Its older transactions move over, from the day the bank's history starts the bank's own are kept, and your edits on those days carry over.
- **Not yet tried against the real service.** It's checked against Enable Banking's API docs and tested with a stand-in. If the first link fails, the error is in the broke container's log (`docker logs brokeless-broke-1`).
### 1. Make an Enable Banking app
1. Sign in at [enablebanking.com](https://enablebanking.com/sign-in/) (they email you a link) and open **Control panel, Applications**.
2. Register a new application:
- Environment: **Production**.
- Key: let the browser generate it. It downloads `<app-id>.pem`. That file name is your app ID. Keep the file safe: it's the key to your bank data.
- Redirect URL, exactly: `http://<your-server>:3003/api/bank/connect/enablebanking/callback` (your `PUBLIC_URL` plus that path).
3. Click **Activate by linking accounts** and link your ING account there. The app is now active in restricted mode: it can read only the accounts you linked.
If the form refuses an `http://` redirect URL, you need https; see the end of this section.
### 2. Give brokeless the keys
Copy the `.pem` file to the server, then add both values to `docker/.env`. The key has to go on one line:
```bash
cd <your brokeless folder>/docker
```
```bash
echo "ENABLE_BANKING_APP_ID=<app-id>" >> .env
```
```bash
echo "ENABLE_BANKING_PRIVATE_KEY=$(awk 'NF {printf "%s", $0}' <app-id>.pem)" >> .env
```
Then delete the copied `.pem` from the server (the key now lives in `.env`) and run Compose Up again.
### 3. Link ING in brokeless
Accounts, Add accounts, **Link your bank**. Pick ING, approve on ING's own page, and you land back in brokeless with your accounts. New transactions come in each time you open the app. Only booked transactions come in; pending ones show up once they're booked.
### If you need https
Enable Banking may only accept an `https://` redirect URL. Then put brokeless behind a reverse proxy with a certificate (for example Nginx Proxy Manager or SWAG on Unraid), pointing at `http://<server>:3003`. brokeless picks up the proxy's https address by itself. Then:
1. In `docker/.env`, change `PUBLIC_URL` to the https address, for example `PUBLIC_URL=https://brokeless.example.nl`. Edit only that line: don't run `setup.mjs` again, that would replace your secrets.
2. Rebuild: `docker compose -f docker/docker-compose.yml up -d --build`.
3. Use `https://brokeless.example.nl/api/bank/connect/enablebanking/callback` as the redirect URL in Enable Banking.
broke's server reaches its own Supabase through `PUBLIC_URL`, so the server must be able to reach that https address too. A local DNS entry pointing the name at your proxy does that.
## Keep it private
- Keep port 3003 and 8025 on your LAN or behind a VPN like Tailscale. Don't forward them on your router.
- Back up `DATA_DIR/db` and `docker/.env` together. The database is useless without the secrets in `.env`.
- `docker/.env` is in `.gitignore`. Never commit it.
## Update
brokeless never updates itself. Your server runs exactly the commit you built.
**Your own changes:** `git pull`, then `docker compose -f docker/docker-compose.yml up -d --build`. Database changes in `supabase/migrations` apply when it starts.
**New broke changes from upstream:** add upstream once, read only:
```bash
git remote add upstream https://github.com/nextwork-projects/broke.git
```
```bash
git remote set-url --push upstream DISABLED
```
Then each time:
```bash
git fetch upstream
```
```bash
git log --oneline main..upstream/main
```
Read what changed (`git show <commit>`). Take everything with `git merge upstream/main`, or single commits with `git cherry-pick <commit>`. Then push to your repo and rebuild.
Things to check in upstream changes: new outside calls (`fetch(` to a new host), new environment variables, and changes to `scripts/start.mjs` or `src/lib/llm/`.
## Use Claude from your own computer
brokeless runs in Docker, so it can't use a Claude login of its own. Instead, Claude Code keeps running on your PC and brokeless sends it questions:
1. On your PC, install Claude Code (`npm install -g @anthropic-ai/claude-code`, or Anthropic's installer) and run `claude` once to sign in.
2. Add `BROKE_HOSTED=1` to `docker/.env` and run Compose Up again.
3. In brokeless: Connect your AI, **Connect my computer**. Run the command it shows on your PC (in PowerShell on Windows) and leave it open. Then pick Claude.
Claude only answers while that command runs. It starts Claude with every tool off, in an empty folder, so it can't touch your files. Works on Windows, macOS and Linux.
## Connect Claude Code (MCP)
brokeless is an MCP server too, so an AI app like Claude Code can read your money summary and fix things for you: find a rule that catches too much, delete it and undo what it did, make better rules, recategorize, mark transfers, merge accounts.
1. In brokeless: Connect your AI, **Connect an AI app (MCP)**, **Make a token**. It shows once.
2. Run the command it shows on your computer:
```bash
claude mcp add --scope user --transport http brokeless https://brokeless.mangavalk.com/api/mcp --header "Authorization: Bearer <token>"
```
3. Start a new Claude Code session and ask, for example: "Which of my brokeless rules catch too much?"
It is summary only, like broke ai: rounded amounts, months not days, names as placeholders (⟨M1⟩, ⟨A1⟩), never single transactions. Changes act on your real data, and Claude says what it will change first. Revoke a token on the same page. With AI switched off in Settings the endpoint refuses.
## How AI stays private
Every AI path goes through one gate. A cloud model gets a summary: rounded amounts, names replaced by tokens. Full detail goes only to a local model, which is what Ollama is here. You can turn AI off in Settings. Each answer runs with no way to change your data.
## Optional things that do go out
All off unless you set them up:
- **Bank feeds:** Enable Banking (UK, Europe, including ING; see [Link your bank](#link-your-bank-ing-and-other-european-banks)), Plaid (US, Canada), Akahu (New Zealand), Basiq (Australia), Belvo (Brazil). These are cloud services by nature. Keys go in `docker/.env`.
- **Cloud AI:** OpenRouter, or your Claude or Codex login. They only ever get the summary.
- **Exchange rates:** set `BROKE_OFFLINE=0` to total accounts in different currencies (rates from the ECB through frankfurter.dev). Without rates, money in another currency than yours is left out of totals. The "Use made-up data" demo bank is in US dollars, so it needs this unless your currency is USD.
- **Real sign-in emails:** set `SMTP_HOST` and friends in `docker/.env` to use your own mail server instead of Mailpit.
## Develop
Without Docker: you need your own Supabase (cloud or self-hosted) and Node 22.
```bash
npm ci
```
```bash
npm run dev
```
Keys go in on http://localhost:3000/setup. `CLAUDE.md` has the privacy rules for AI coding tools. Checks:
- `npm run lint` and `npx tsc --noEmit`
- `node src/lib/statement.test.ts`, `node src/lib/origin.test.ts` and the other `src/lib/*.test.ts` files
- `npm run migrate`: apply database changes now. They also apply on start.
`npm run app` starts it like broke's own installer does, and fast-forwards from your repo (`origin`) on each start. Set `BROKE_NO_AUTO_UPDATE=1` to turn that off.
## Licence
MIT, like broke. Copyright (c) 2026 NextWork, see [LICENSE](LICENSE). `docker/db/*.sql` come from Supabase's self-hosting setup (Apache-2.0).