Oikos

Self-hosted family planner for small households

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

Features

Module	Description
Tasks	Shared tasks with deadlines, priorities, subtasks, and recurring schedules. Kanban board with touch-friendly one-tap status buttons.
Shopping Lists	Collaborative lists organized by aisle. Import ingredients from meal plans in one click.
Meal Planning	Weekly drag-and-drop planner. Export ingredient lists directly to your shopping list.
Recipes	Create, duplicate, and scale reusable recipes. Pre-fill meal slots from a recipe or save any meal as a recipe.
Calendar	Two-way sync with Google Calendar (OAuth) and Apple iCloud (CalDAV). Subscribe to any public ICS/webcal URL with per-subscription color and visibility.
Budget	Track income and expenses with recurring entries, monthly trends, and CSV export. 35 predefined categories plus custom ones. Supports 15 currencies.
Notes & Contacts	Colored sticky notes with Markdown support. Contact directory with vCard import/export.
Birthdays	Birthday tracker with automatic annual calendar events, age display, profile photos, and 1-day-before reminders.
Reminders	Time-based reminders on tasks and calendar events. In-app notification badge.
Family	Assign family roles and profile pictures per member.
API Tokens	Named Bearer / X-API-Key tokens for external integrations. SHA-256-hashed at rest, with optional expiry. OpenAPI 3.0 spec at /api/v1/openapi.json.

Design & Technology

• Liquid Glass UI — translucent surfaces, backdrop blur, module-tinted overlays, spring animations — inspired by Apple's Liquid Glass, built in pure CSS
• PWA — installable on any device, works offline, dark mode, responsive from phone to desktop
• Privacy First — SQLCipher AES-256 encrypted database, fully self-hosted, zero telemetry
• Zero Build Step — pure ES modules, no bundler, no transpiler, no framework
• Multilingual — 14 languages with automatic locale detection (de, en, es, fr, it, sv, el, ru, tr, zh, ja, ar, hi, pt)

Quick Start

Option A — Web Installer (recommended)

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

Open http://localhost:8090 in your browser. The wizard configures your .env, starts Docker, and creates your admin account. 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          # 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          # set SESSION_SECRET and DB_ENCRYPTION_KEY
docker compose up -d --build
docker compose exec oikos node setup.js

Open http://localhost:3000 and sign in with the admin credentials you created above.

New to Docker? The Installation Guide covers Docker setup, HTTPS, backups, and troubleshooting step by step.

Tech Stack

Documentation

Installation	Spec & Data Model	Contributing	Security	Changelog	Backlog

License

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