casher

casher

Self-hosted personal finance tracking. One container, one SQLite file, no cloud.

Built because Firefly III models every merchant as an account and makes you walk through double-entry bookkeeping to record a coffee. casher keeps the parts that make the numbers correct and throws away the ceremony.

What it does

• Home — a dashboard of widgets you pick, reorder and resize yourself.
• Accounts — current accounts, savings, cash, credit cards, PayPal, loans.
• Income — a hub plus recurring sources and one-off entries.
• Spending — a hub plus recurring fixed costs and one-off expenses. The list groups by category, payment instrument, charged account, payee, fixed/one-off or week, with a subtotal and share on every group header.
• Savings — savings accounts, pots inside them, targets and a forecast of when each pot will be full.
• Funding plan — how much has to move from your income account to every other account this month so each can pay its own charges.
• Insights — where the money goes, by category, payee and payment method.

The ideas that make it work

Money is integer cents. Never a float.

A merchant is not an account. Only real accounts are accounts. The counterparty is a payee string plus a category, so recording an expense is two fields. Only a transfer carries two accounts.

Recurring rules generate real transactions. A rule is a template that materialises Transaction rows with status planned, which turn into booked once their date passes. The future is a forecast you read off the same tables as the past, and a single month can deviate — the electricity bill that came in 30 € higher is just an edited instance.

The financial month does not have to start on the 1st. Set month_start_day to the day your salary lands and every figure follows that cycle.

One number per page, the rest unfolds. Each screen leads with a single figure; supporting detail sits behind collapsed panels so nothing shouts at you on arrival. Accounts and categories can be created from wherever you happen to need them — no detour through the settings.

Free to spend:

  income
− fixed costs       (everything a recurring rule produced)
− savings           (moved to a savings account — gone from the budget,
                     but not spent: net worth is unchanged)
= budget for free spending
− variable spending (one-off expenses)
= free to spend

Two refinements: a transfer that clears a credit card or repays a loan is not counted (the card's purchases were counted when they happened), and a non-monthly fixed cost can be spread — a 600 €/year insurance premium then weighs 50 € on every month instead of destroying January.

Payment instruments. Each account has a settlement mode:

So "20 € at a shop, paid with PayPal, debited from the current account" is one entry: pick PayPal, and the charge lands on the current account while the insights still show it as PayPal.

The funding plan. Fixed costs are charged to whichever account actually pays them. For each account casher works out what it will be charged this period, adds its buffer, subtracts what is already on it and what you have already scheduled — what is left is what still has to move from the income account. One button books those transfers.

Running it

Development:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env          # set CASHER_SECRET_KEY
.venv/bin/uvicorn app.main:app --reload --port 8099

Container:

docker compose up -d --build   # published on :40020

A fresh instance starts empty: one admin user created from CASHER_ADMIN_USER / CASHER_ADMIN_PASSWORD, a starter set of categories, and nothing else. Change the password in Settings afterwards and turn on TOTP if the instance is reachable from the internet.

First steps in a new instance: create the account your salary lands on and tick "Income lands here", add the accounts you pay from, then add your recurring income and fixed costs. The funding plan and the free-to-spend figure fall out of that on their own.

Everything lives in data/casher.db, uploaded background images in data/uploads. Back up that volume and you have backed up casher. Settings → Export CSV dumps every transaction.

Layout

app/
  models.py            schema — accounts, transactions, rules, goals
  money.py             cent parsing and formatting
  common.py            period + sync helpers every router uses
  services/
    periods.py         the financial month
    accounts.py        balances, settlement resolution
    recurring.py       rules -> generated transactions
    budget.py          free-to-spend maths
    distribution.py    the funding plan
    analytics.py       category / payee / instrument breakdowns
  routers/             one module per area; entries.py owns all form handling
templates/             Jinja2, one folder per area, widgets/ for the dashboard
static/                one stylesheet, one script, no CDN

Not built yet

• Bank import (CSV / CAMT / FinTS)
• Firefly III migration
• Loan amortisation schedules