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 when you’re ready.

Or hand it to an agent

Paste this into Claude Code, Cursor, Codex, or another capable agent:

Help me install Tidings. Read https://docs.gettidings.com/install.md first, then walk me through it.

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

   No published image for your platform yet? The same command builds from source instead — first run takes a few minutes.

2. Open the dashboard.

   http://localhost:8000

Set your timezone

Tidings defaults to America/Los_Angeles. Change it under Settings → Timezone (or the timezone key in data/config.json before first launch), and it applies to the whole instance. Details and the changing-it-later caveat are in settings.

Wire up your own data

When you move to real data, three pages cover the 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 off until you add a key

Tidings can use OpenAI to label each transaction’s category. Adding an OPENAI_API_KEY turns on two switches under Settings → Intelligence — categorization and email rescue — and either can be turned back off. Categorization sends only the amount and the merchant name, never the account number, card number, or balance; email rescue sends the subject and body of an email no parser could read, so OpenAI can read the transaction out. Run without a key and nothing leaves your machine.

Common gotchas

The three failures people hit first — port 8000 already in use, IMAP authentication, and permissions on data/ — are covered in Docker setup’s troubleshooting, each with its one-line fix.

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