How to use Sempa and how to host it. Features remain the same in browser, the Windows desktop app and Android, except where noted.
Sempa is under active development. It's stable for everyday use — people run it as their daily task manager — but new features and fixes land often, and upgrading rebuilds the container. Before you come to rely on it, turn on automatic backups. They take about two minutes to set up and mean a bad upgrade, a disk failure, or a fat-fingered restore can never cost you your data.
In the app, open Settings → Backup & Restore and:
To recover, return to the same screen and Restore from a backup file. Database migrations run automatically on startup, so a backup taken on an older version restores cleanly after you upgrade. Full options are in Backup & restore below.
After signing in, a short setup wizard helps you connect email and calendar — all optional, and addable later in Settings. You land on Today, ready to plan.
On desktop and web, a left sidebar pairs a pinned Search with a sectioned nav rail: Today and This Week up top, then Rituals (Plan Day, Shutdown), Inbox (Email, Reminders) and Library (Backlog, Journal). Change the grouping (Spaces · Plan·Focus·Review · Flat) and section style (Labels or Dividers) in Settings → Appearance. The rail footer holds a utility icon row (Settings, light/dark, desktop Widget), an update indicator when a new version is available, the sync status, and an account chip (avatar · email · Sign out).
The day view's right-hand panel is a tabbed dock — Schedule · Inbox · Jira · Goals — beneath a mini-calendar.
On mobile, a bottom tab bar carries Today, Week, Journal, Lists and More. The More sheet is grouped: a quick row (Settings, light/dark, Widget, AI Import), a Plan group (Plan Day, Schedule, Backlog, Search), an Inbox group (Email, Reminders, Jira, Shutdown) and your account. A + button creates a task on list screens. To install the PWA, open your Sempa instance in a browser and choose “Install” / “Add to Home Screen”.
Command palette. Press Cmd/Ctrl+K anywhere to open a keyboard-first launcher — jump to any screen, run an action (including Import with AI), or fall through to search for any query you type.
Mobile gestures. Swipe a task left to reschedule it to tomorrow. Long-press the app icon for New task / Plan day / Shutdown quick actions. And Share-to-Sempa: share a link or text from any app and Sempa turns it into a task (optionally running it through AI Import).
The core unit. Open any task to edit it in a side panel (desktop) or bottom sheet (mobile).
Plan Day is a guided morning ritual: write your intention, see what carried over from yesterday, and pull tasks from your backlog into today. Your previous day's note is shown for continuity.
The Week board is a Kanban across seven days — drag tasks between days and statuses. Set Weekly Objectives (the handful of outcomes that matter) and link tasks to them so progress is visible. Drag an objective onto a day to create a task already linked to it; completing an objective's linked task(s) auto-completes the objective. Copy as Markdown exports a clean, single-heading bulleted list. Dedicated screens let you plan the week and run a weekly review — capturing wins, challenges and your next focus — and both surface as gentle in-app prompts.
Shutdown is an end-of-day ritual: tick off what's done, reschedule what isn't, record a win and an optional reflection, and close the day cleanly. It all collects in the Journal — a searchable timeline of your daily intentions and reflections and your weekly wins, challenges and next focus. Optionally show reflections inline on day and week screens (Settings → Appearance → contextual reflections).
A quiet, rotating quote appears with the logo animation when you open Sempa, and flashes briefly when you complete a task — a small bit of encouragement, never fixed on screen. Turn it off or edit the list (add, remove, reset) in Settings → Account.
A single list of everything not yet scheduled — your inbox of ideas. Pull items into days as you plan.
Hit Focus on any task to start a Pomodoro. A persistent timer widget then follows you across the whole app, showing the task, the countdown, and how long you've actually spent vs. your estimate — so an overrun is obvious in the moment, not a surprise at the end. The timer survives navigation and reloads.
Sempa is built with time-blindness in mind — we routinely think a task will take 20 minutes when it takes an hour — and logs honest time, not the countdown: when you finish, it shows the measured time and asks you to confirm or adjust it (including “didn't really work on it”), so only the number you confirm is recorded. Complete a task with no timer running and a gentle “How long did that take?” prompt catches it (it skips very quick tasks and backs off when you're clearing a burst).
Tune all of it — the completion prompt, the day-capacity limit, per-activity default times, and your timer lengths — in Settings → Time tracking.
Search looks across tasks, objectives and journal entries. On list views, switch into tag filter mode to show only tasks with a given tag. When filtering by a tag, export the resulting list as CSV or clean Markdown from the Search page.
The Lists view holds standalone, undated checklists — an ongoing groceries list, a packing list, materials to buy. Add items, drag to reorder, and tick them off (checked items grey out and strike through in place; untick to restore). Lists live independently of any day, so a half-checked list just waits for you.
Lists are local-first like the rest of Sempa — add, reorder and check items with no connection; they sync when you're back online.
Create daily, weekly or monthly templates (Settings → Recurring Tasks). Instances generate automatically; editing one occurrence customises just that one while the series rolls forward. To change the template itself — title, notes, tags, estimate or schedule — use its edit button in Settings → Recurring Tasks; changes flow to upcoming occurrences while anything you've already customised stays put.
The Today view is a rolling board of day columns with today anchored at the left edge. Scroll left into the past and right into the future continuously — no week boundaries to page through. The ‹ › header buttons and the j / k keys jump a week at a time; Today re-anchors on the current day.
The Windows desktop app includes a floating Widget — a compact, always-on-top panel showing what's up next, with quick checkboxes and a quick-add box. Open it from the sidebar icon rail or a single click on the system-tray icon (double-clicking the tray icon opens the main window).
See events beside your tasks in the Schedule tab of the right-hand dock. Connect Google and Fastmail calendars, a CalDAV server (with optional push of your time-blocks back to it), or subscribe to any ICS / webcal feed.
The Email screen lets you triage incoming mail and convert messages to tasks, with the original linked.
Sempa can use a small language model to take the friction out of capture and review. Everything runs on a model you host yourself (Ollama), on your own server — no data is ever sent to any third party, there's no API key, and there are no usage costs or rate limits. If the model is unavailable, every feature quietly falls back to the manual path; nothing breaks.
| Feature | Where | What it does |
|---|---|---|
| AI Import | Lists button · Ctrl/⌘+Shift+I · command palette · mobile More menu | Turn a URL (a recipe, an article) or pasted text into a task with ordered steps as sub-tasks plus a companion checklist of items (ingredients, supplies). Structured recipes (schema.org) are read directly without the model; everything else goes through it — always into an editable preview (place it today or in the backlog) before saving. The source link is stamped onto the task. Each entry point is individually toggleable. |
| Natural-language quick add | ✦ on a task title | Type “lunch with Sam thu 1pm 30m #personal” and it fills in the title, date, time, estimate and tags. |
| Suggest tags | ✦ on the tag editor | Recommends tags only from your existing tag set, so your taxonomy stays consistent. |
| Break into subtasks | ✦ on a task | Splits a task into a few concrete, ordered subtasks you can keep or edit. |
| Title cleanup & summary | Email / Jira import | Tidies imported subjects and issues into concise, action-oriented titles with a rough estimate. |
| Plan my day | Plan Day | Suggests a focused order for today's tasks around your calendar events — applied only when you click. |
| Draft weekly review | Week Review | Drafts your wins / challenges / next focus from the week's completed tasks and objectives; you edit before saving. |
| Reflection prompts | Shutdown | Offers a couple of context-aware end-of-day questions based on what you did and didn't finish. |
Connect Jira to import your assigned issues as tasks — full guide in docs/JIRA.md. In brief:
Configured in Settings → Notifications. Set Remind me (date + time) on any task for a hard alert with Mark done and Snooze 1h actions; tapping it opens the task. Reminders are deduplicated, so re-arming or snoozing won't double-fire. Choose delivery channels independently:
Pick from 10 calm alert tones (each with a ▶ preview), and set the times for the in-app weekly planning and daily shutdown routine prompts — calm in-app banners, not OS alarms.
The desktop and Android apps are local-first: they keep a local copy of your data, so the app stays fully usable with no connection. Changes queue and sync automatically when the server is reachable; a sync indicator shows status. Plain web (in a browser, not installed) talks directly to the server.
One Sempa server can hold more than one person. Manage people in Settings → Users — an admin can add users and reset passwords, and each person can change their own password. Google sign-in and the bootstrap env-login both map to a user account.
Everything is private by default. Tasks, lists and weekly objectives each have a Private / Shared toggle: flip one to Shared and everyone on the server can see and edit it (sharing a task cascades to its sub-tasks; sharing a list cascades to its items). Un-sharing removes it from everyone else again while keeping it yours. Your daily plan, shutdown journal and focus sessions stay owner-only, always. It's built for a household sharing what it wants and keeping the rest to itself — not for large teams.
In Settings → Backup & Restore: automatic daily backups at an hour you choose with a retention count, optional encryption with a passphrase, and one or more destinations (each with a Test button). Run now for an on-demand backup, Download the latest archive, or Restore from a file. Migrations run automatically on startup, so a backup taken on an older version restores cleanly after you upgrade; your data lives in the sempa_data Docker volume.
| Destination | What you need |
|---|---|
| Local folder | Nothing — kept on the server (the default). That's one copy on one disk, so pair it with an off-server destination. |
| S3-compatible | Bucket, region, access key ID + secret (AWS S3, Backblaze B2, MinIO…), optional key prefix. |
| WebDAV / Nextcloud | The WebDAV URL plus a username + password (or app password). |
| Google Drive | A connected Google account (see below). Backups land in a dedicated Sempa Backups folder. |
Google Drive backup reuses your server's Google OAuth client — the same one that powers Google sign-in and Gmail import (see Configuration). Once that's configured, add a Google Drive destination and click Connect Google Drive; you'll consent in Google and come back to Sempa. Sempa requests only the drive.file scope, so it can see only the files it creates — never the rest of your Drive.
On the same screen, Restore from a downloaded archive (enter the passphrase if it was encrypted). A restore replaces your current data, so it asks you to confirm first. Because migrations run on startup, an archive from an older Sempa restores cleanly onto a newer one.
In Settings → Appearance, choose from six full-interface themes — Terracotta (default), Forest, Plum, Slate, OLED Black and Ocean — each with a live preview. Every theme has a light and dark mode, except OLED Black, which is dark-only. The same page has a text-size slider, the sidebar grouping and section style controls for the desktop nav rail, and the contextual reflections toggle. Your choice is remembered per device and applied before first paint — no flash on load.
Sempa checks GitHub for newer releases and surfaces them in-app: a subtle indicator in the nav rail, an update toast (Download · What's new · Later), and Settings → About — current version, update channel (Stable / Beta), an automatic-checks toggle, when it last checked, and a manual Check for updates. On web and desktop this points you to the installer. Optional silent background self-update for the desktop app is opt-in.
Sempa is built to be safe to run yourself. It's free and open source under the AGPL-3.0, so anyone can read exactly what it does, and it follows the OpenSSF Best Practices standard (passing) — a recognised checklist for how securely an open-source project is run.
Every change is checked automatically before it ships: CodeQL scans the code, govulncheck and Trivy watch for known vulnerabilities in dependencies (the build fails on serious ones), and gitleaks guards against committed secrets. The parsers that read untrusted input — calendar feeds, imported email, recurrence rules and AI output — are continuously fuzzed, with tests run under Go's race detector. Dependencies are kept current by Dependabot, the full test suite runs on every change, and the main branch is protected so code only lands through reviewed pull requests. Release downloads are signed with cosign, Docker base images are digest-pinned, and the server runs as a non-root container.
For your own setup, two steps do most of the work: reach Sempa over Tailscale so nothing is exposed to the public internet, and turn on encrypted backups. The plain-language Security overview covers the rest, and the full OpenSSF assessment and SECURITY.md document every criterion and scan.
| Section | What you configure |
|---|---|
| Account | Sign-in, profile |
| Integrations | Gmail, Fastmail, Jira, CalDAV, task inbox, and AI (local model: connection, model download/remove, per-feature toggles) |
| Calendars | Connected calendars, ICS/webcal feeds, show/hide, colours |
| Tags | Create, rename, recolour tags |
| Recurring Tasks | Daily / weekly / monthly templates |
| Notifications | Reminders, delivery channels, sounds, routines, home timezone |
| Time tracking | Completion prompt, day capacity, per-activity default times, focus/break lengths |
| Backup & Restore | Schedule, encryption, destinations (Local · S3 · WebDAV · Google Drive) |
| Appearance | Theme, light/dark, text size, sidebar grouping, contextual reflections, system font / accent / title bar |
| About | Version, update channel, automatic checks, “Check for updates” |
| Key | Action |
|---|---|
| Cmd/Ctrl+K | Open the command palette (navigate, run actions, search) |
| Ctrl/⌘+Shift+I | AI Import (URL / text → task) |
| n | New task (day view) |
| e | Edit the hovered task |
| t | Go to today |
| j / k | Previous / next week |
| ? | Show shortcuts help |
| Esc | Close the open dialog |
You need Docker and Docker Compose (v2). The installer asks a few questions (URL, auth method, and optional extras like Tailscale, email-to-task and local AI), writes your config, builds the image and starts the container — about two minutes.
Open the URL it prints and follow the setup wizard. Everything else — email, calendar and Jira accounts — is connected later in Settings. To upgrade: git pull && docker compose build && docker compose up -d. Your data lives in the sempa_data volume and is preserved across rebuilds.
Don't want to build from source? Every release also publishes a multi-arch (amd64/arm64) server image to the GitHub Container Registry — install.sh offers a “pull prebuilt image” option, or pull it directly:
The server container runs as a non-root user (uid 10001) and is built on digest-pinned base images.
Tailscale is the easiest way to reach Sempa securely from all your devices without exposing it to the public internet — no port forwarding, automatic HTTPS, and only your devices can connect.
Configuration lives in two local files: .env (URL, port — for Docker Compose substitution) and .env.local (secrets, loaded into the container). Authentication supports Google Sign-In (OAuth — the same client also powers Gmail import) and username + password; leaving the password unset disables auth entirely (fine for a trusted Tailscale-only install).
| Variable | Purpose |
|---|---|
| APP_URL | Where Sempa is accessible (no trailing slash) |
| HOST_PORT | Port to expose on the host (default 9001) |
| GMAIL_CLIENT_ID · GMAIL_CLIENT_SECRET | Google OAuth client — one client powers sign-in, Gmail import and Google Drive backup. Authorise both the /api/v1/auth/google/callback and /api/v1/backup/drive/callback redirect URIs, and publish the app to Production to avoid 7-day token expiry (see Backup) |
| SEMPA_TIMEZONE | Home IANA timezone (e.g. America/Toronto); sets when the day rolls over for recurring tasks, the board and the digest. Auto-detected by install.sh; also editable in Settings → Notifications |
| SEMPA_ALLOWED_EMAILS | Comma-separated allow-list for Google sign-in |
| SEMPA_USERNAME / _PASSWORD | Username + password auth (unset disables auth) |
| TS_AUTHKEY | Auth key for the Tailscale sidecar |
| OLLAMA_BASE_URL | Local model endpoint for AI title cleanup (empty = off) |
| OLLAMA_MODEL | Model for title cleanup (default qwen2.5:1.5b) |
| EMAIL_FORWARD_TOKEN · SMTP_ALLOWED_SENDERS | Email-to-task webhook token; sender allow-list |
| VAPID_SUBJECT · FCM_KEY_PATH | Web Push contact; Android push key |
| SMTP_PORT | Port for the built-in inbound SMTP server (default 2525) |
| COMPOSE_PROFILES | Set to ai to start the optional ollama service (written automatically when you choose local AI) |
| INBOX_POLL_INTERVAL | How often to poll the email inbox (default 1m) |
| CALENDAR_POLL_INTERVAL | How often to refresh ICS feeds + the Fastmail calendar (default 15m; empty disables) |
Full details, integration setup and all optional variables are in the repository README.