Crumbs by Bretzel

A self-hostable, offline-first note-taking app that respects your privacy. Part of the Bretzel app universe.

Install

Docker (Recommended)

docker compose up -d

Open http://localhost:3000 and create your admin account on first visit.

With SSO (optional)

# docker-compose.yml
services:
  crumbs:
    image: ghcr.io/bretzel-app/crumbs:latest
    ports:
      - "3000:3000"
    volumes:
      - crumbs-data:/data
    environment:
      - ORIGIN=https://notes.example.com
      - AUTH_OIDC_ISSUER=https://authentik.example.com/application/o/crumbs/
      - AUTH_OIDC_CLIENT_ID=your-client-id
      - AUTH_OIDC_CLIENT_SECRET=your-client-secret
      - AUTH_OIDC_DISPLAY_NAME=Authentik
    restart: unless-stopped

volumes:
  crumbs-data:

Google and GitHub OAuth are also supported. See docs/AUTH.md for all providers and setup guides.

Manual (Node.js)

git clone <repo-url> crumbs && cd crumbs
pnpm install
pnpm build
DATABASE_URL=./data/crumbs.db ORIGIN=http://localhost:3000 node build

Development

pnpm install
pnpm dev

Run make help to see all available commands, or use pnpm directly:

pnpm test          # Unit + E2E tests
pnpm check         # Type checking
pnpm build         # Production build

Features

• Rich notes with Markdown, checklists, image attachments, and 12 color themes
• Organize with #tags, pinning, archive, and trash
• Full-text search across titles, content, and tags
• PWA — installable, works offline via IndexedDB + LWW CRDT sync
• MCP server — let AI assistants (Claude Code, etc.) manage your notes
• Multi-user auth (Argon2) with optional OAuth/SSO (Google, GitHub, OIDC)
• Docker deployment with a single command

See docs/FEATURES.md for detailed feature documentation.

Tech Stack

Layer	Technology
Framework	SvelteKit 2 (Svelte 5 runes)
Language	TypeScript (strict)
UI	Tailwind CSS 4
Database	SQLite (better-sqlite3) + Drizzle ORM
Client DB	IndexedDB (idb)
Sync	LWW CRDTs
Auth	Argon2 + session cookies
Testing	Vitest + Playwright
Container	Docker (multi-stage)
CI/CD	GitHub Actions

Documentation

Document	Description
Features	Detailed feature list and behavior
Architecture	Local-first sync design, tech rationale, DB schema
Auth	Password auth, OAuth/SSO setup (Authentik, Keycloak, etc.)
Deployment	Docker, Node.js, reverse proxy, backups, env vars
API	REST API reference (auto-generated)
Contributing	How to contribute
Security	Vulnerability reporting policy
Changelog	Release history

CI/CD

• CI — lint, type check, unit tests, E2E tests, Docker build on every push/PR
• Release — builds and pushes Docker image on v* tags

Configure registry via GitHub Secrets: REGISTRY_URL, REGISTRY_USER, REGISTRY_TOKEN.

License

MIT