Syllogic

About Syllogic

Syllogic is an open-source personal finance app for self-hosters who want control over their data without giving up a polished product. Track balances, spending, recurring charges, and trends, import and export CSVs, and optionally enable AI categorization.

Why self-hosters care

• Keep financial data on infrastructure you control
• Start with Docker, Railway, or CasaOS instead of building from scratch
• Export your data whenever you want
• Use AI categorization only if it helps your workflow

Try it now

• Live demo: app.syllogic.ai/login?demo=1
• Quick guide: START_HERE.md
• Roadmap: ROADMAP.md

What works today

• Balances and cash flow: dashboard views, savings trends, and cash-flow breakdowns
• AI categorization: optional OpenAI-powered categorization with rule-based fallback
• Recurring spend tracking: identify subscriptions and recurring charges
• Category analytics: compare spending over time and spot trends
• Transfer and reimbursement linking: avoid double-counting across accounts
• CSV import/export: ingest bank exports and keep your data portable
• MCP server: connect compatible LLM clients for technical finance workflows

Quick Start

Self-Hosted (Docker)

One-liner (requires root, Docker, and Docker Compose):

curl -fsSL https://github.com/syllogic-ai/syllogic/releases/latest/download/install.sh | sudo bash

Or manually:

1. Clone and configure:

   Linux/macOS:

   git clone https://github.com/syllogic-ai/syllogic.git
   cd syllogic
   cp deploy/compose/.env.example deploy/compose/.env
   # Edit deploy/compose/.env — set POSTGRES_PASSWORD, BETTER_AUTH_SECRET, INTERNAL_AUTH_SECRET
   

   Windows (PowerShell):

   git clone https://github.com/syllogic-ai/syllogic.git
   cd syllogic
   copy deploy\compose\.env.example deploy\compose\.env
   # Edit deploy\compose\.env — set POSTGRES_PASSWORD, BETTER_AUTH_SECRET, INTERNAL_AUTH_SECRET
   

2. Start:

   Linux/macOS:

   ./scripts/prod-up.sh
   

   Windows (PowerShell or CMD):

   .\scripts\prod-up.bat
   

3. Open http://localhost:8080 and create your account.

For advanced configuration (TLS, custom domains, MCP server), see deploy/compose/README.md.

Railway (One-Click)

The template configures everything through Railway Shared Variables — one place that every service reads from. The required secrets (POSTGRES_PASSWORD, BETTER_AUTH_SECRET, INTERNAL_AUTH_SECRET, DATA_ENCRYPTION_KEY_CURRENT) are auto-generated at deploy time, so a default deploy needs no manual input.

Optionally set these Shared Variables to enable extra features:

• OPENAI_API_KEY (enables AI categorization)
• LOGO_DEV_API_KEY (enables company logos)

For full Railway setup details, see deploy/railway/README.md. Maintainers publishing the template: see deploy/railway/TEMPLATE.md.

Shared Demo Login Link

For public demo environments, you can share a login URL that prefills demo credentials:

https://your-app-domain.com/login?demo=1

Syllogic public demo:

https://app.syllogic.ai/login?demo=1

Set these frontend environment variables on that deployment:

• NEXT_PUBLIC_DEMO_EMAIL
• NEXT_PUBLIC_DEMO_PASSWORD

Optional auth throttling (recommended for public demos):

• AUTH_RATE_LIMIT_ENABLED=true
• AUTH_RATE_LIMIT_WINDOW_MS=60000
• AUTH_RATE_LIMIT_MAX_ATTEMPTS_PER_WINDOW=30
• DEMO_AUTH_RATE_LIMIT_MAX_ATTEMPTS_PER_WINDOW=10
• DEMO_AUTH_RATE_LIMIT_GLOBAL_MAX_ATTEMPTS_PER_WINDOW=120

Other Deployment Methods

Method	Use case	Docs
CasaOS	Home lab / NAS users	deploy/casaos/

How the reference instance is hosted

The deployment configs in this repo — deploy/railway/, deploy/compose/, deploy/casaos/ and the railway.*.toml files — describe how you can host Syllogic. They are the supported, documented paths, and the one-click Railway template is built from them.

They do not describe how app.syllogic.ai is wired. That instance runs on Coolify on a single server, and it is itself a self-hosted deployment of this same code — it just happens to also serve the public demo login. Coolify is not listed above because it is not packaged as a template here; if you want it, the deploy/compose/ stack is the closest starting point.

One difference worth knowing if you are building a client against it: on that instance only the web app and the MCP endpoint are publicly reachable. The FastAPI service is private, and the web app proxies to it — so a mobile or third-party client authenticates against the web origin, not against the API directly. A self-hosted deployment can expose the API however it likes; nothing in the code requires this arrangement.

Configuration

Variable	Description	Required
POSTGRES_PASSWORD	PostgreSQL password	Yes
BETTER_AUTH_SECRET	Auth session signing key	Yes
INTERNAL_AUTH_SECRET	App-to-backend signed auth	Yes
DATA_ENCRYPTION_KEY_CURRENT	Field-level encryption key	Recommended
OPENAI_API_KEY	AI transaction categorization	No
LOGO_DEV_API_KEY	Company logo lookup	No

Generate secrets with openssl rand -hex 32. For encryption keys: openssl rand -base64 32.

Optional Features Behavior

OPENAI_API_KEY — AI-powered categorization via OpenAI (GPT-4o-mini by default).

• When set: Transactions are categorized using the LLM for high accuracy.
• When not set: Falls back to keyword-based matching (e.g., "Tesco" → Groceries, "Netflix" → Entertainment). The keyword matcher uses a 70% confidence threshold.

LOGO_DEV_API_KEY — Company logo lookup via logo.dev.

• When set: Merchant logos are fetched and displayed for transactions and accounts.
• When not set: No logos are shown; the feature is silently disabled.

Full variable reference is available in deploy/compose/.env.example.

Architecture

• Next.js 16+ (TypeScript, Drizzle ORM, BetterAuth, shadcn/ui, Recharts)
• FastAPI (SQLAlchemy 2.0, Celery + Redis, OpenAI)
• PostgreSQL 16, Redis 7, Docker Compose

Both services share a single PostgreSQL database. The frontend handles all CRUD via Server Actions; the backend handles data enrichment, bank sync, and background jobs.

People & ownership

Syllogic models a household as a set of people belonging to one user. Accounts, properties, and vehicles can have one or more owners with optional shares (a NULL share means equal split). Holdings inherit ownership from their account. The Syllogic MCP read tools accept person_ids to scope results and attribute share-weighted amounts.

Investments & holdings

Track brokerage and crypto holdings with portfolio summaries and history. The Syllogic MCP exposes read tools for holdings, portfolio summary/history, and symbol search.

Development

Quick start for contributors:

Option A: Prebuilt Mode (Recommended)

Everything runs in Docker using prebuilt images. Easiest setup for full-stack testing.

1. Clone and configure:

git clone https://github.com/syllogic-ai/syllogic.git
cd syllogic
cp deploy/compose/.env.example deploy/compose/.env
# Edit deploy/compose/.env — set INTERNAL_AUTH_SECRET, BETTER_AUTH_SECRET
# Keep DATABASE_URL=postgresql://...@postgres:5432/... (Docker internal)

2. Start the stack:

# Linux/macOS
./scripts/dev-up.sh --prebuilt

# Windows
.\scripts\dev-up.bat prebuilt

3. Open http://localhost:8080

Option B: Local Mode

Infrastructure runs in Docker, frontend runs on host. Best for frontend development with hot reload.

1. Clone and configure:

git clone https://github.com/syllogic-ai/syllogic.git
cd syllogic
cp deploy/compose/.env.example deploy/compose/.env
# Edit deploy/compose/.env — set INTERNAL_AUTH_SECRET, BETTER_AUTH_SECRET

2. Start infrastructure:

# Linux/macOS
./scripts/dev-up.sh --local

# Windows
.\scripts\dev-up.bat local

This starts PostgreSQL, Redis, and Celery workers, installs dependencies, runs migrations, and creates frontend/.env.local with the required environment variables.

3. Start the Next.js dev server:

cd frontend
pnpm dev

4. (Optional) Start the backend (required for CSV import and other backend features):

cd backend
uvicorn app.main:app --reload

5. Open http://localhost:3000

Note: Local mode runs only infrastructure. CSV import and other backend features require starting the backend (step 4) or using prebuilt mode.

See CONTRIBUTING.md for full setup instructions and code style guidelines.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).