koto

A self-hosted space for a small, closed group — family, close friends — to talk and share posts, to-dos and a calendar.

koto is a dedicated web client on top of Matrix, plus a ready-made homeserver setup. Matrix does the hard parts (accounts, sync, media, push); koto hides everything a general-purpose chat client exposes — homeserver fields, room directories, federation, encryption settings — so members only see the handful of things the group actually uses.

The interface is currently in Japanese only.

Features

• Rooms — any member opens a room (a group chat, a diary, a trip plan…); the list shows the most recently active first with unread counts. Every room has Slack-style threads, photos, reactions (emoji or the group's own images), edit and delete, a typing indicator, and posts with a title, text and up to four photos
• Read state for the author — nothing when you're alone, read / unread for two people, a reader count with a who-has-read list for three or more
• To-do lists — anyone adds and ticks items; who finished what is recorded
• Calendar — month view, recurring events, and a countdown to the next one
• Members — the admin adds and removes accounts from the app itself
• Settings — the admin renames the site, tabs and labels, and picks the reaction set
• Installable PWA with push notifications; each member chooses what the lock screen shows

How it is closed

• No federation: the homeserver talks to no other Matrix server
• No public registration: the first person creates the admin account with a setup password; after that, only the admin can add members
• No room directory, no invitations: having an account is membership

Because it is standard Matrix underneath, the data is not locked in: the rooms' messages, photos, reactions and read receipts are ordinary Matrix events.

Quick start

You need a Linux host with Docker Compose v2, two DNS names pointing at it (one for the app, one for the homeserver) and a reverse proxy that terminates TLS. docs/traefik has a ready-to-use Traefik setup.

git clone <this repository> koto && cd koto
docker network create web             # shared with the reverse proxy
cp .env.example .env
$EDITOR .env                          # domains and passwords
./scripts/init.sh                     # renders the homeserver config
docker compose up -d
./scripts/check.sh                    # every line should say "ok"

Then open https://<KOTO_DOMAIN>/. On a fresh server koto shows 初期設定 (first-time setup): enter the setup password from .env and choose your own username and password. You become the admin; add everyone else from the member list.

docs/deployment.md covers every step in detail, including push notifications, other reverse proxies, rootless Docker, upgrades and backups.

Documentation

Deployment	Installing, configuring, upgrading and backing up
Troubleshooting	What each failure looks like and how to fix it
Architecture	How koto maps onto Matrix
Development	Running the app locally, tests, repository layout
Migration	Importing data from the earlier Supabase-based koto

Repository layout

compose.yaml    the whole stack: web app, Synapse, PostgreSQL, Sygnal (push)
.env.example    every setting, in one place
scripts/        init, health check, account and push-key helpers
server/         Synapse and Sygnal configuration templates
client/         the web app (Vite, React, TypeScript, matrix-js-sdk)
docs/           guides, and the example Traefik setup

License

GNU Affero General Public License v3.0. If you run a modified version for others to use, you must offer them its source.