Oikos

The self-hosted family planner. Private, offline-capable, and beautiful.

→ Install  ·  Screenshots  ·  Docs

_{Toggle GitHub light/dark mode to see both themes  ·  View all screenshots}

Oikos is a self-hosted web app that keeps your household organized — tasks, groceries, meals, calendar, budget, and more — in one private place, without cloud accounts or subscriptions. Runs as a Docker container on any home server or NAS. Accessible on every device with a polished mobile-first PWA interface.

Each module is independent. Use what fits, skip what doesn't.

---

Modules

Tasks	Shared tasks with deadlines, priorities, subtasks, recurring schedules, multi-member assignment, Kanban, and mobile-friendly bulk controls.
Shopping	Collaborative lists organized by aisle. Touch-safe quick add, swipe gestures, and meal-plan import in one click.
Meals	Weekly drag-and-drop planner with direct export to your shopping list.
Recipes	Create, duplicate, and scale recipes. Pre-fill meal slots or save any meal as a recipe.
Calendar	Google Calendar (OAuth) and CalDAV sync (iCloud, Nextcloud, Radicale). ICS subscriptions, recurring events, file attachments, and readable month/agenda views.
Documents	Upload and organize family files. Folders, tags, per-document visibility, drag-and-drop.
Budget	Income, expenses, recurring entries, trends, CSV export. Split Expenses for shared costs with automatic debt simplification.
Housekeeping	Manage household staff — schedules, check-in/out, payments, chores, supply requests.
Notes & Contacts	Colored sticky notes with Markdown. Contact directory with CardDAV sync.
Birthdays	Birthday tracker with automatic calendar events, age display, and custom reminders.
Family	Member profiles with roles, photos, phone, email, and birthday — synced to Contacts and Birthdays.
Reminders	Time-based notifications on tasks and calendar events with in-app badge.
API Tokens	Named Bearer / X-API-Key tokens for integrations. OpenAPI 3.0 spec included.
Backup	Manual and scheduled database backup and restore, with automatic pre-restore rollback.

---

Design & Technology

• Disciplined Liquid Glass UI — readable work surfaces, subtle translucent navigation, spring animations, and module-tinted overlays — built in pure CSS
• PWA — installable on any device, works offline, responsive from phone to desktop, with tuned mobile navigation, touch targets, and dark mode
• Privacy First — fully self-hosted, SQLCipher AES-256 encrypted database, zero telemetry
• Zero Build Step — pure ES modules, no bundler, no transpiler, no framework
• Multilingual — 16 languages with automatic locale detection (de, en, es, fr, it, sv, el, ru, tr, zh, ja, ar, hi, pt, uk, pl)

---

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  ·  Modules  ·  Contributing  ·  Security  ·  Changelog  ·  Backlog

---

License

MIT — see LICENSE.

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