Yarukoto

A self-hosted todo app. One container, one SQLite file, your data on your own server.

The server serves both the API and the web client, so a single docker compose up gives you a working instance. The same codebase builds the iOS, Android and Mac apps via Expo.

Documentation · Live demo · Website · Home Assistant integration · Roadmap

Status: working and usable, but young. One household per server: everyone gets their own account and private lists, and signs in by QR code rather than password. See Limitations before trusting it with anything important.

Features

• Lists, folders, tags and saved filters, with Today, Upcoming, Inbox, Plan and Calendar views.
• Quick add with natural syntax: pay rent fri 6pm #home !high ~admin sets the date, time, tag, priority and list.
• Native apps for iPhone, Android and the Mac, plus the web app the server hosts.
• A household: everyone gets private lists and an Inbox, shares the lists they choose, and signs in by QR code.
• Offline-tolerant sync: the app never waits on the network, and changes push when the server is reachable.
• Trash, history and daily backups, so a mistake is recoverable.
• Home Assistant to-do lists through a HACS integration, and AI assistants through a built-in MCP server.

Quick start

Requires Docker with Compose v2. The compose file pulls the prebuilt ghcr.io/wyne/yarukoto image (amd64 and arm64).

git clone https://github.com/wyne/yarukoto.git
cd yarukoto
echo "YARUKOTO_TOKEN=$(openssl rand -hex 32)" > .env
docker compose up -d

Open http://localhost:8080 and paste the token from .env. The installation guide covers updating and building from source, and there are separate steps for a Synology NAS.

Documentation

• Self-hosting: configuration, HTTPS and reverse proxies, backups
• Reference: REST API, limitations
• Development: setup, architecture and sync, feature compatibility, iOS and Android builds, the Mac app, the Windows app

The docs are Markdown in docs/, so a change and its documentation land in the same pull request. Merging to main publishes them.

Repo layout

client/             Expo + React Native client for web, iOS, Android, and Mac
server/             Fastify + better-sqlite3 API server
packages/domain/    Types and domain logic shared by the client and server
windows/            Tauri shell that packages the web build as a Windows app
docs/               The documentation site (Starlight)

The JavaScript projects are one npm workspace. Run npm install once at the repository root, then use the root scripts or target an individual package with npm --workspace.