<img src="https://capsule-render.vercel.app/api?type=waving&height=240&color=0:0a1020,35:12244a,70:1d4ed8,100:7c3aed&text=Dispatch&fontSize=70&fontColor=ffffff&fontAlignY=40&desc=A%20self-hosted%20task%20app%20that%20you'll%20love%20using.&descSize=18&descAlignY=62&animation=fadeIn" alt="Dispatch banner" /> <a href="https://github.com/nkasco/DispatchTodoApp"><img alt="Version" src="https://img.shields.io/github/package-json/v/nkasco/DispatchTodoApp?style=for-the-badge&label=Version&color=f59e0b" /></a> <a href="https://github.com/nkasco/DispatchTodoApp/pkgs/container/dispatchtodoapp"><img alt="Docker Pulls" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fghcr-badge.elias.eu.org%2Fapi%2Fnkasco%2FDispatchTodoApp%2Fdispatchtodoapp&query=%24.downloadCount&label=Docker%20Pulls&color=0ea5e9&style=for-the-badge" /></a> <a href="https://github.com/nkasco/DispatchTodoApp/commits/main"><img alt="Last Updated" src="https://img.shields.io/github/last-commit/nkasco/DispatchTodoApp?style=for-the-badge&label=Last%20Updated&color=22c55e" /></a> <a href="#quick-start">Quick Start</a> • <a href="#feature-tour">Feature Tour</a> • <a href="#tech-stack">Tech Stack</a> • <a href="#local-development---prerequisites">Local Dev</a>

<img src="./docs/assets/dispatch-dashboard-latest.png" alt="Dispatch dashboard screenshot" /> Clean dark UI, fast keyboard flow, project rollups, deadline focus, and daily dispatch planning in one screen.

Why It Feels Great

| | | | --- | --- | | Runs locally (Docker/Node) with SQLite on the host. | Next.js + Node server runtime with SQLite data persisted on the host (dispatch.db) or Docker volume. | | One workspace for everything | Tasks, projects, notes, and dispatches stay connected. | | Keyboard-friendly UX | Fast actions, global search, and shortcut support keep flow uninterrupted. | | Built for real execution | Deadline focus, progress rollups, and upcoming work are always visible. |

Runtime and Storage Model

Runs locally (Docker/Node) with SQLite on the host.

Dispatch requires a server runtime (Next.js + Node) to function.
Data is stored in a SQLite database file on the host machine (or Docker volume when containerized).
The browser acts as a client only.
Dispatch does not use IndexedDB or browser-based primary storage, and it is not a purely client-side PWA.

Feature Tour

Dashboard: instant visibility into active tasks, notes, dispatches, deadlines, and project activity.
Tasks: status + priority + due dates + project links.
Projects: progress rollups and scoped task lists.
Notes: markdown editing, preview, and export.
Dispatch: daily planning surface with rollover support.
Personal Assistant (Beta): streaming AI chat powered by Vercel AI SDK, with in-app actions via a local MCP (Model Context Protocol) tool server.
Search: global search across tasks, notes, and dispatch records.
Recycle Bin: restore or permanently remove archived items.
Auth: GitHub OAuth and local development credentials.

Tech Stack

Quick Start

Docker Setup (Recommended)

Dispatch includes production launchers that create/update .env.prod and run Docker Compose.

Prerequisites:

Docker Desktop (Windows/macOS) or Docker Engine + Compose plugin (Linux)
docker available on your PATH, with Docker running before setup
Internet access to pull the default image (ghcr.io/nkasco/dispatchtodoapp:latest)

Use one of the following:

.\dispatch.ps1 setup

./dispatch.sh setup

GitHub Auth in Docker:

During setup, choose Enable GitHub OAuth sign-in? and provide AUTH_GITHUB_ID / AUTH_GITHUB_SECRET.
Set NEXTAUTH_URL to the public URL users will open in the browser.
If this runs on a dedicated server in your home/lab network, use the server hostname or LAN IP in NEXTAUTH_URL instead of localhost.
In GitHub OAuth app settings, set the callback URL to:
- <NEXTAUTH_URL>/api/auth/callback/github
- Example: http://dispatch-server:3000/api/auth/callback/github

Local Development - Prerequisites

Use this section only if you are running Dispatch locally with Node.js (npm run dev, npm run build, npm run start).

Node.js 20.9+ (LTS recommended).
Node includes npm, which is required for local development commands.
Git (recommended for pulling updates).
If native module install fails (for better-sqlite3), install platform build tools:
- Windows: Visual Studio Build Tools (C++ workload)
- macOS: Xcode Command Line Tools (xcode-select --install)

Manual Setup (Alternative)

1. Install

npm install

2. Configure env

Create .env.local (local Node.js/dev runtime only):

Docker setup uses .env.prod, not .env.local.

# Required for NextAuth
AUTH_SECRET=your_random_secret
NEXTAUTH_URL=http://localhost:3000

# GitHub OAuth (optional)
AUTH_GITHUB_ID=your_github_oauth_client_id
AUTH_GITHUB_SECRET=your_github_oauth_client_secret

# Optional (defaults to ./dispatch.db)
DATABASE_URL=./dispatch.db

3. Migrate database

npm run db:migrate

4. Run app

npm run dev

Open http://localhost:3000.

npm run dev starts both services:

Next.js app on http://localhost:3000
Dispatch MCP server on http://localhost:3001 (used by Personal Assistant tool calling)

Dev Login (Optional)

Seeded account: test@dispatch.local / test
- Run npm run db:seed first to create the seeded account.

Dispatch is an independent open-source project and is not affiliated with any other software using the name Dispatch.

DispatchTodoApp

Install / Use

README