The open-source sync + AI server for Kaisho. Run your own to track time from your phone, desktop, and terminal, all syncing through a server you control. Free, self-hostable on plain PostgreSQL, no plans or tiers.
Prefer not to run a server? Point the apps at a Kaisho-hosted instance instead. It runs this same image; the only difference is the URL.
+-----------------+ +--------------------+
| Mobile PWA | <--> | Express API |
| (React/Vite) | | kaisho-cloud | --> OpenRouter
| served at /m | | api/ | (optional AI)
+-----------------+ +----------+---------+
|
+-----------------+ | +-----------------+
| Desktop / CLI | <---+---> | PostgreSQL |
| (sync token) | | (your data) |
+-----------------+ +-----------------+
Two parts:
api/— Node.js/Express server: auth (self-owned JWT + API keys), clocks, sync, AI gateway, WebSocket, cron worker.mobile/— React 19 PWA served at/m(sign up, track time on your phone).
Data lives in plain PostgreSQL; auth is self-owned (no Supabase). There is no billing in this repo.
- Start/stop timers and book time from any device
- Cross-device sync (desktop, phone PWA, CLI) on one account
- API-key sync token for the desktop/CLI, JWT for the mobile PWA
- Password reset via HMAC-signed tokens (+ optional email)
- WebSocket push for real-time updates across devices
- Optional AI gateway proxying to OpenRouter, with a per-instance cap
- Optional scheduled AI runs (the cron worker)
git clone https://github.com/ridingbytes/kaisho-cloud.git
cd kaisho-cloud
cp .env.example .env # set POSTGRES_PASSWORD, DATABASE_URL, JWT_SECRET
docker compose up --build -dThis starts Postgres, runs the schema migration, and serves the API +
mobile PWA on port 3000. Open http://localhost:3000/m to sign up and
track time. For phone use you need HTTPS — see self-hosting below.
| Document | Contents |
|---|---|
| docs/self-hosting.md | Run your own server + track time on your phone |
| docs/architecture.md | System design, auth, sync, AI |
| docs/development.md | Local development |
| deploy/hosted/ | Traefik + Postgres production stack |
pnpm install
cd mobile && pnpm install && pnpm build && cd ..
cp .env.example .env
pnpm dev # needs a reachable DATABASE_URL
npm test # unit testsAGPL-3.0-or-later, see LICENSE. Copyright (c) 2026 RIDING BYTES GmbH.
The desktop app, the iOS app and the website are MIT. This repo is the server, and it is copyleft on purpose: anyone may run it, self-host it and change it, but offering a modified version to others over a network means publishing those changes. Using it unmodified, hosted for yourself or your team, carries no such obligation.
Section 13 is the reason GET / reports license and
source. If you run a modified build as a service, point
SOURCE_URL at your fork, so the offer of source actually
leads to the code you are running.