SubSync

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.3 · 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.3.exe        # Windows portable
release/SubSync 1.1.3-arm64.dmg  # macOS Apple Silicon
release/SubSync-1.1.3.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

Copyright © 2026 Evan Newman.

SubSync is free software licensed under the GNU Affero General Public License v3.0 only. You may use, study, modify, and redistribute it under that license. Modified versions offered to users over a network must also provide those users access to the corresponding source code.

SubSync is provided without warranty. Third-party components remain under their respective licenses; see THIRD_PARTY_NOTICES.md.