sure-sync

Privacy-first, Docker-based local ingestion pipeline for syncing OFX transaction files into the Sure (Maybe) Finance.

Sure Sync is a Docker-based, localised automation service that simplifies importing bank transactions into the Maybe Sure finance platform. It is ideal for users whose banks do not provide public APIs, offering a secure, file-driven workflow for financial data while keeping all sensitive credentials, configuration, and data local.

The current release includes a web dashboard for live status, processing statistics, and account mapping management.

Key Workflow:

• Consume OFX files – Reads exported bank statements from a local consume folder for processing.
• Account mapping – Maps bank accounts to Sure accounts using a user-defined YAML configuration (<v2.0.0) dashboard.
• Deduplication – Checks for and skips transactions that have already been processed to prevent duplicates.
• Transaction creation – Creates new transactions in Maybe Sure automatically.
• Archiving – Moves processed OFX files to a local archive folder for record-keeping.
• Localised control – Users maintain full control of credentials, configuration, and data without storing secrets in the repository.

Features

• Localised, file-based workflow (no need for bank APIs)
• Docker-first deployment
• Automatic deduplication of transactions
• Easy account mapping through YAML (<v2.0.0) dashboard
• Web dashboard for monitoring stats and managing account mappings
• Persistent state storage in a host-mounted data directory
• Secure local credentials via .env

Components

Sure Sync is designed with a modular architecture where the ingestion worker and web dashboard can run independently.

• worker – Handles OFX ingestion, parsing, deduplication, and syncing to Sure.

View the latest Docker image: ghcr.io/shrestha-bishal/sure-sync-worker:latest

• web (optional) – Provides monitoring, logs, and account mapping UI.

View the latest Docker image: ghcr.io/shrestha-bishal/sure-sync-web:latest

Deployment Modes

Standalone Mode (worker):

Runs only the ingestion worker without the UI.

• Headless execution
• Ideal for servers or background processing
• No dashboard required

docker pull ghcr.io/shrestha-bishal/sure-sync-worker:latest

Full Stack Mode (worker + web):

Runs both worker and web dashboard via Docker Compose.

• Worker + UI together
• Includes easy file and transaction monitoring
• Includes account mapping interface

docker pull ghcr.io/shrestha-bishal/sure-sync

or

docker pull ghcr.io/shrestha-bishal/sure-sync-worker:latest
docker pull ghcr.io/shrestha-bishal/sure-sync-web:latest

Prerequisites

• Docker
• Docker Compose
• Sure account with API access
• Exported OFX files from your bank

---

Quick Start

• Create the directory

mkdir ~/.docker-apps/sure-sync
cd ~/.docker-apps/sure-sync

• Download configuration files from the latest release:

Download the docker-compose.yml

wget -O docker-compose.yml https://github.com/shrestha-bishal/sure-sync/releases/latest/download/docker-compose.yml

Download the example.env

wget -O .env.example https://github.com/shrestha-bishal/sure-sync/releases/latest/download/example.env

• Configure environment variables

mv example.env .env

or

mv .env.example .env 

Edit .env to set your Sure API credentials and folder paths. The main .env variables are:

Variable	Description	Example
CONSUME_PATH	Local folder to scan for OFX files	./consume/
DATA_PATH	Host folder for persistent state and stats	./data/
API_URL	Sure API base URL	http://host.docker.internal:3000/api/v1/
API_KEY	Sure API key with read/write access	your-api-key
LOOKUP_INTERVAL	Poll interval for scanning files (seconds)	5

To generate an API key in Maybe Sure, navigate to Accounts > Settings > API Key, select Create New Key, choose Read / Write permissions, and save the generated API key and copy the API base URL up to /api/v1/.

• Start the service

Make sure the Maybe Sure is running before composing.

docker compose up -d

The service will automatically process any OFX files in the consume/ folder.

Service behavior

• The worker service watches CONSUME_PATH for OFX files.
• Processed files are moved to processed/ and failures to failed/.
• Account mappings are managed through the web dashboard.

Web Dashboard (optional)

• Access the dashboard at http://localhost:9000 or your configured port
• Use Accounts to add mapped bank accounts
• Dashboard also shows processing statistics and current app state

Note: Please restart the stack using docker compose up -d after account addition (this will be streamlined in future update).

Logs

• Provides real-time visibility into system activity, including transaction processing, errors, and background job execution.

Contributing

• Fork the repo, make changes, and submit a pull request.
• Report bugs or feature requests via GitHub issues.

License

MIT License. See LICENSE for details.

Funding & Sponsorship

Sure Sync is an open-source tool developed and maintained to automate the import of bank transactions into the Sure finance platform. It simplifies financial data workflows and ensures reliable, localised syncing for users without public bank APIs.

If you or your organisation find this project valuable, please consider supporting its ongoing development. Your sponsorship helps sustain long-term maintenance, improve features, enhance documentation, and maintain compatibility with future Sure API updates while keeping the project free and open for the community.

As a token of appreciation, sponsors may have their logo and link featured in the project README and documentation. Priority support, early access to new features, or custom enhancements may also be offered where appropriate.

Support Options

---

Author

Bishal Shrestha

© 2026 Bishal Shrestha, All rights reserved