This is the whole install, start to finish, for someone who has Docker and has never run a finance app themselves. Oikonome is one Compose stack: the app, a worker, Postgres and Redis. It runs on a Raspberry-Pi-class box, a NAS, a spare laptop or a $6 VPS.
What you need
- A Linux machine with Docker (or Podman) and Compose. Windows works inside WSL2 with Docker Desktop's WSL integration; macOS works with Docker Desktop or OrbStack but is lightly tested.
git,curlandopenssl. If any are missing the installer says so, shows the install command for your distro, and re-checks. It never installs anything without asking.- Modest hardware. It runs on a NAS, a Raspberry-Pi-class box or a $6 VPS. The optional local model for categorization wants more: the installer picks a model by available RAM (about 5 GB for the 7B model on a 12 GB host, about 1 GB for the small one).
Install
git clone https://github.com/oikonome/oikonome.git && cd oikonome
./oikonome.sh install
The installer generates the database passwords and the encryption master key, builds the images and starts everything. Re-running it is always safe: it keeps your .env and your data. When it finishes it prints the URL, http://localhost:8042 by default (it picks the next free port if that one is taken).
Want to see the product working before you connect anything real? ./oikonome.sh demo stands up a separate throwaway instance full of synthetic data on its own port.
The setup wizard
Open the URL. The wizard creates your account and walks five steps, every one skippable and resumable later from the green Finish setup pill:
- Connect an account. Self-host offers the full provider grid: SimpleFIN, your own Plaid or MX keys, community scripts, or file imports. More on each below.
- Bills. The app waits for your bank's full history to arrive (up to two years, minutes after linking), then proposes the recurring bills and paychecks it found. You approve or reject each one. Rejections are remembered.
- Budgets. Food and Everything-else per month plus expected income, pre-filled from your data. That is all the daily verdict needs.
- Email delivery. Give the instance an outbound SMTP account so the daily email can reach you. Guides for the common providers are in the step.
- Done. Choose email, push, both or neither, and the hour.
Then you land on Today. The first daily email goes out the next morning.
Bank sync without giving anyone your password
Three ways in, and you can mix them per account:
- SimpleFIN ($1.50/mo, paid to SimpleFIN, not to us). You authorize your banks at SimpleFIN Bridge and paste one token into Oikonome. Your bank credentials are never on your server.
- Your own Plaid or MX keys. If you have an account with either aggregator, paste the client ID and secret; their pricing applies and the app stores the keys envelope-encrypted under your master key.
- Files and scripts. CSV, OFX/QFX, Quicken QIF, Mint and YNAB exports, PDF statements. For sources no aggregator reaches (Amazon order history, a 401(k) portal, a crypto exchange), community scripts run on your machine and push in through a scoped token that can write transactions and nothing else.
You can link two sources to one real account. The healthiest one serves the data and the other stands by, so a flaky aggregator never leaves you blind or double-counts.
Backups, upgrades, undo
./oikonome.sh is the single manager. Run it with no arguments for a menu; the commands you will actually use:
./oikonome.sh backup # pg_dump into ./backups
./oikonome.sh restore <file> # replace the database (asks first)
./oikonome.sh install # also upgrades: pull, rebuild, migrate
./oikonome.sh status # containers, port, version, last backup
./oikonome.sh reset-password <email> # locked out, no SMTP needed
Put backup on a cron and copy the directory somewhere else; the dump contains everything, and the master key is in docker/.env, which you should also keep a copy of. A dump without the key cannot decrypt the bank tokens, which is the point.
Putting it on the internet
You do not have to. The email works from a box on your LAN, and the mobile app can reach it over Tailscale or WireGuard. If you want it public, ./oikonome.sh https sets up TLS and the reverse-proxy guide covers Caddy, nginx and Traefik. Passkeys and TOTP are built in; turn one on before you expose it.
What it will not do
It will not phone home. No telemetry, no analytics beacon, no update check that reports your version. Categorization runs on a local model if you enable it, so transaction text never goes to an outside AI provider. Merchant logos are fetched once by your instance and cached there. The daily email carries its chart inside the message, so opening it cannot be tracked either.
If you would rather not run it
The hosted version at oikonome.com is the same software with the servers, backups and bank plumbing handled: $6.99/mo or $69/yr, 30 days free, no card. Nothing is gated either way, and you can export everything and move between the two.