Oikos

Self-hosted family planner for small households

Tasks · Shopping Lists · Meal Planning · Recipes · Calendar Sync · Budget · Notes · Contacts · Birthdays · Reminders

_{Toggle GitHub light/dark mode to see both themes.}

Highlights

Task Management: Shared tasks with deadlines, priorities, subtasks, recurring schedules, Kanban view with one-tap status buttons for touch devices

Shopping Lists: Collaborative lists with aisle categories and one-click import from meal plans

Meal Planning: Weekly drag-and-drop planner with ingredient lists and shopping export

Recipes: Create, edit, duplicate, and delete reusable recipes with notes, a recipe link, and per-ingredient categories. Pre-fill meal slots from a recipe and scale ingredient quantities; save any meal as a recipe with one click.

Calendar Sync: Two-way sync with Google Calendar (OAuth) and Apple iCloud (CalDAV); subscribe to any public ICS/webcal URL with per-subscription color, private/shared visibility, and automatic sync

Budget Tracking: Income and expenses, recurring entries, DB-backed expense categories with subcategories (35 predefined + custom), configurable currency (15 currencies), monthly trends, CSV export

Notes & Contacts: Colored sticky notes with Markdown, contact directory with vCard import/export

Birthdays: Personal birthday tracker with automatic annual calendar events, age calculation, profile photos (≤ 5 MB), and 1-day-before reminders — auto-synced, no manual setup needed.

Reminders: Time-based reminders on any task or calendar event, with an in-app notification badge. Birthday reminders are created automatically.

Family Management: Assign family roles (Dad, Mom, Child, etc.) and upload profile pictures per family member.

API Tokens: Admins can create named Bearer / X-API-Key tokens for external integrations; tokens are SHA-256-hashed at rest, support optional expiry and revocation. OpenAPI 3.0 specification available at /api/v1/openapi.json.

Zero Build Step: Pure ES modules, no bundler, no transpiler, no framework. Ships what you write.

Privacy First: SQLCipher AES-256 encrypted database, fully self-hosted, zero telemetry

Liquid Glass UI: Translucent surfaces with backdrop blur, module-tinted glass overlays, spring animations - inspired by Apple's Liquid Glass, built in pure CSS

PWA Native Feel: Installable on any device, works offline, dark mode, responsive from phone to desktop

Multilingual: German, English, Spanish, French, Italian, Swedish, Greek, Russian, Turkish, Chinese, Japanese, Arabic, Hindi, and Portuguese UI with automatic locale detection

Quick Start

Option A — Web Installer (recommended):

git clone https://github.com/ulsklyc/oikos.git && cd oikos
node tools/installer/install-server.js

Then open http://localhost:8090 in your browser. The wizard configures your .env, starts Docker, and creates your admin account — no manual steps needed. Requires Node.js 18+ on the host.

Option B — pre-built image (no clone required):

curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/ulsklyc/oikos/main/.env.example
cp .env.example .env     # edit .env — set SESSION_SECRET and DB_ENCRYPTION_KEY
docker compose up -d
docker compose exec oikos node setup.js

Option C — build from source:

git clone https://github.com/ulsklyc/oikos.git && cd oikos
cp .env.example .env     # edit .env — set SESSION_SECRET and DB_ENCRYPTION_KEY
docker compose up -d --build
docker compose exec oikos node setup.js

Then open http://localhost:3000 and log in with the admin credentials you set in the previous step. Add family members from Settings.

New to Docker? The Installation Guide walks you through every step: From installing Docker to HTTPS setup, backups, and troubleshooting.

Tech Stack

Documentation

Installation	Spec & Data Model	Contributing	Security	Changelog	Backlog

License

_{Built with care for families who value privacy and simplicity.}