Quickstart

Try Tidings in about a minute, with no real bank accounts. The demo runs from a seeded SQLite database — no IMAP credentials, no AWS, no external services. Click around, then wire up your own data once the shape feels right.

Run the demo

1. Clone the repository and start the stack.

   git clone https://github.com/tvhahn/tidings.git
   cd tidings
   docker compose up -d

2. Open the dashboard.

   http://localhost:8000

The default is demo mode — a seeded SQLite database (data/demo.db) of sample transactions. No real accounts touched, no IMAP connection, nothing sent anywhere.

Set your timezone

Tidings defaults to America/Los_Angeles. Change it under Settings → Timezone. The selector lists every IANA zone your browser supports; Detect from browser picks your local one in a click.

The setting is instance-wide — it applies to every browser pointing at this dashboard, not just the one you set it from. It persists to the timezone key in data/config.json, so you can also set it before first launch by editing that file.

Changing timezone after you have ingested transactions is safe but imperfect: new transactions bucket in the new zone, while existing rows keep their original local-time sort-key prefix.

Wire up your own data

Once the demo feels right, three pages cover the real wiring, in order:

1. Self-hosting with Docker — copy .env.example to .env, set demo_mode: false in data/config.json, and run the stack against your own SQLite database.
2. Email setup — create a dedicated Gmail account, generate an App Password, and point your bank alerts at it.
3. Notifications — pick a push or SMS provider. The recommended default is ntfy: free, no account, works on iOS and Android.

AI categorization is opt-out

Tidings can use OpenAI to label each transaction’s category. It is on when OPENAI_API_KEY is set, off otherwise, and you can toggle it under Settings → Intelligence. When a built-in parser recognizes the bank, only the amount and the merchant name go to OpenAI — never the account number, card number, or balance. When an email can’t be parsed and AI is on, its subject and body are sent so OpenAI can read the transaction out. Run without an OpenAI key and nothing leaves your machine.

Common gotchas

• Port 8000 already in use — change the host side of the port mapping in docker-compose.yml (for example "8001:8000") and open http://localhost:8001.
• IMAP poller can’t connect — Gmail needs an App Password, not your account password, and 2-Step Verification has to be on. Email setup walks through it.
• Permission errors on data/ — the named volume is owned by the container user. If you switched between a bind mount and the named volume, reset with docker compose down -v.

For the full JSON API while the stack is running, see the API reference.