A local-first subscription command center for streaming, music, gaming, and media services.

SubSync helps you track plans, billing cadence, renewal dates, and monthly spend in one place — without cloud accounts or third-party data hosting. Everything runs on your machine: a NestJS API, a Next.js dashboard, and a SQLite database bundled inside a desktop app.

Current version: 1.1.2 · Platforms: Windows portable · macOS Apple Silicon · Linux AppImage

Most subscription trackers assume a hosted backend. SubSync is built for people who want full control of their data:

• Local-only storage — subscriptions, settings, and import history stay in a SQLite file on your device
• No login required — single-user desktop workflow with no external auth dependency
• Automatic imports — connect Gmail to pull billing emails, or paste/import receipts manually
• Renewal awareness — dashboard KPIs, upcoming renewals, and OS notification reminders

• Monthly equivalent spend and spend-by-category breakdown
• Upcoming renewals list sorted by date, with per-subscription snooze
• Active subscription count and duplicate-plan detection
• Recent activity feed of subscription status changes
• Inline add/delete and quick navigation to subscription details

• Full CRUD for subscriptions (plan, amount, currency, interval, renewal date, payment method)
• SubscriptionEvent audit log per subscription (created, status changed, renewal)
• Pre-seeded catalog for Spotify, YouTube Premium, Netflix, Disney+, and Hulu

• Gmail OAuth — read-only access to scan billing and subscription emails automatically
• Manual email import — paste billing email content to create or update subscriptions via heuristic parsing
• Provider connect — persist connection state for OAuth-capable and email-based providers
• Scheduled Gmail sync every 6 hours when connected

• Configurable lead time (days before renewal)
• Desktop / browser push notifications delivered through the Electron shell or web client
• Hourly background worker queues reminders for active and trial subscriptions
• Unified notification preferences in Settings (shared by the UI and reminder worker)

• CSV / JSON export of subscriptions (/api/data/export/subscriptions)
• One-click SQLite backup and restore from Settings

• Windows portable .exe, macOS .dmg / .zip for Apple Silicon, and Linux AppImage
• Unsigned today; Windows SmartScreen may warn and macOS requires right-click Open until SubSync is signed
• In-app auto-update from GitHub Releases (electron-updater) on Windows and Linux; macOS updates are disabled until signing
• Bundles API (127.0.0.1:43100) and packaged web UI (127.0.0.1:43101)
• Applies SQLite migrations automatically on first launch (tracked in a _migrations ledger)
• Native OS notification polling while the app is running

1. Download the latest build for your platform from GitHub Releases: SubSync *.exe for Windows, SubSync *-arm64.dmg for macOS Apple Silicon, or SubSync-*.AppImage for Linux.
2. Launch it. Windows users should read docs/windows-portable-quickstart.md; macOS and Linux users should read docs/macos-linux-desktop-quickstart.md.
3. Open Dashboard to review spend and renewals.
4. Open Connections to link Gmail or import billing emails.
5. Open Settings to set reminder lead time and enable desktop notifications.

• Node.js 22+ (the desktop migration tests use the built-in node:sqlite module)
• npm 10+

git clone https://github.com/ejames-dev/SubSync.git
cd SubSync
npm install

Copy environment variables and initialize the database:

cp .env.example .env
cp .env apps/api/.env
npm run prisma:migrate --workspace api
npm run prisma:generate --workspace api
npm run prisma:seed --workspace api

Start the API and web UI (in separate terminals):

npm run dev:api    # http://127.0.0.1:43100/api
npm run dev:web    # http://127.0.0.1:3000

Open http://127.0.0.1:3000/dashboard for local web development. The packaged desktop app still uses 127.0.0.1:43101 for its bundled web server.

Or launch the full Electron shell:

npm run build:desktop
npm run dev:desktop

Gmail integration requires Google Cloud OAuth credentials. Configure:

GOOGLE_OAUTH_CLIENT_ID="your-client-id"
GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret"
GOOGLE_OAUTH_REDIRECT_URI="http://127.0.0.1:43100/api/gmail/callback"

Authorized redirect URI in Google Console must match GOOGLE_OAUTH_REDIRECT_URI.

SubSync/
├── apps/
│   ├── api/          # NestJS 10 REST API (Prisma + SQLite)
│   └── web/          # Next.js 14 App Router UI
├── desktop/
│   ├── main.cjs      # Electron entry — starts API, web, notifications
│   └── prepare-dist.mjs
├── packages/
│   └── types/        # Shared TypeScript contracts (@subscription-tracker/types)
└── docs/             # Architecture, roadmap, release notes

All routes are prefixed with /api.

See .env.example for the full list.

npm run dist:desktop

Local packaging produces the current platform's artifact:

release/SubSync 1.1.2.exe        # Windows portable
release/SubSync 1.1.2-arm64.dmg  # macOS Apple Silicon
release/SubSync-1.1.2.AppImage   # Linux

The Release GitHub workflow builds Windows, macOS Apple Silicon, and Linux artifacts on matching hosted runners and uploads them to a draft GitHub Release when a v* tag is pushed or the workflow is dispatched manually.

Release checklist: docs/release-checklist.md

docker-compose.yml is legacy (Postgres) and is not required for local development.

• Code signing for Windows and macOS builds
• Intel or universal macOS builds
• Spend-by-category chart on the dashboard
• Expanded provider catalog and provider-specific email parsers
• Budget alerts and spend forecasting

Full plan: docs/release-roadmap.md

• Builds are unsigned: Windows SmartScreen may warn, and macOS requires right-click Open on first launch
• macOS builds are Apple Silicon only and do not auto-update until signing is configured
• Per-provider Spotify/YouTube OAuth is simulated — Gmail is the first real OAuth integration
• Email-channel reminders are logged but not sent (no SMTP); push/desktop notifications are the working path
• No cloud sync or multi-user support

Evan Newman · GitHub