DispatchTodoApp: Why Devs Are Ditching Notion for This Self-Hosted Powerhouse

Your task data doesn't belong in someone else's cloud. Yet here you are—paying monthly subscriptions for bloated productivity tools that track your every click, slow to a crawl with "offline mode" that barely works, and force you into mouse-heavy workflows that break your coding flow. Sound familiar?

The dirty secret of modern productivity apps? They're built for managers, not makers. Developers need speed. We need our hands on the keyboard. We need our data where we control it. And we absolutely need tools that don't phone home to Silicon Valley every time we mark a task complete.

Enter DispatchTodoApp—a self-hosted task application that's quietly becoming the weapon of choice for developers who refuse to compromise. Built by nkasco with an obsessive focus on keyboard-centric workflows and local-first SQLite persistence, Dispatch isn't just another todo app. It's a declaration of independence from the SaaS treadmill.

What makes this tool genuinely exciting isn't just what it does—it's what it doesn't do. No vendor lock-in. No subscription creep. No mysterious AI training on your project plans. Just pure, blazing-fast task management that respects your workflow and your data sovereignty.

Ready to see why the GitHub community is pulling this image by the thousands? Let's dissect what makes DispatchTodoApp the most compelling self-hosted productivity tool to emerge in 2024.

What is DispatchTodoApp?

DispatchTodoApp (or simply "Dispatch") is an open-source, self-hosted task management application designed specifically for technical users who demand control over their productivity stack. Created by developer nkasco and actively maintained on GitHub, Dispatch represents a deliberate rejection of the cloud-first, subscription-heavy model that dominates the productivity space.

At its architectural core, Dispatch runs on Next.js 16 with React 19 and TypeScript 5, using SQLite as its primary data store. This isn't a browser-based toy that loses your data when you clear cookies—it's a full server-side application where your dispatch.db file lives persistently on your host machine or Docker volume. The browser is purely a client, which means your data stays where you put it.

The project is currently trending among developers for several converging reasons:

• The self-hosting renaissance: Post-Reddit-API-pocalypse, developers are reclaiming infrastructure
• AI integration anxiety: Dispatch's local MCP server approach to AI keeps tool calling in your network
• Keyboard culture resurgence: Tools like Vim, Helix, and now Dispatch prove mouseless workflows aren't dead
• Docker maturity: One-command deployment that's actually production-ready

What separates Dispatch from the endless graveyard of "I built a todo app" projects is its holistic execution philosophy. This isn't just task tracking—it's a complete productivity surface with projects, notes, daily planning ("Dispatches"), and even an experimental AI personal assistant that operates through local infrastructure rather than external APIs holding your data.

The GitHub repository shows healthy activity with recent commits, growing Docker pull counts, and a clear roadmap that suggests this is a living project, not abandonware. For developers burned by tools that pivot to enterprise or get acqui-killed, that maintenance signal matters enormously.

Key Features That Justify the Hype

Let's dissect what makes Dispatch technically compelling beyond the marketing copy.

Local-First SQLite Architecture

Unlike Notion, Todoist, or even Obsidian's cloud-dependent sync, Dispatch stores everything in a single SQLite file. This means:

• Zero network latency for data operations
• Trivial backups: Copy one file
• Queryable data: Attach any SQLite tool for custom analytics
• No sync conflicts: Your data has one source of truth—your server

Keyboard-Centric UX Design

Every interaction is optimized for developers who live in terminals and IDEs. Global search, fast actions, and comprehensive shortcuts eliminate the context-switching penalty of reaching for a mouse. The workflow mirrors the efficiency of tools like Linear or GitHub's command palette, but applied to personal productivity.

Unified Workspace Model

Tasks, projects, notes, and daily dispatches aren't siloed modules—they're interconnected entities. Project rollups automatically aggregate task progress. Deadlines surface across contexts. Notes link to projects without fragile URL schemes.

Daily Dispatch Planning with Rollover

The eponymous "Dispatch" feature provides a dedicated daily planning surface where unfinished work automatically rolls forward. This eliminates the demoralizing "yesterday's incomplete tasks" audit that kills morning momentum in other tools.

Streaming AI Assistant (Beta)

Here's where it gets technically interesting: Dispatch integrates Vercel's AI SDK for streaming chat, but routes tool execution through a local MCP (Model Context Protocol) server running on port 3001. This means:

• AI suggestions without sending your task list to OpenAI's training pool
• In-app actions that modify your data through your infrastructure
• Extensible tool system for custom integrations

Markdown-First Notes with Export

Notes use standard Markdown with live preview and export capability. No proprietary format lock-in—your knowledge remains portable.

GitHub OAuth + Local Auth Flexibility

Production deployments can use GitHub OAuth for team access, while local development uses simple credential auth. The seeded test@dispatch.local account enables immediate experimentation without OAuth configuration.

Real-World Use Cases Where Dispatch Dominates

1. The Indie Hacker's Command Center

Solo developers juggling multiple projects need visibility without overhead. Dispatch's project rollups show exactly which initiatives are stalled, while daily dispatches enforce ruthless prioritization. The SQLite backend means your business data never touches third-party servers—critical when you're pre-revenue and paranoid.

2. Homelab Infrastructure Tracking

Self-hosters managing complex home infrastructure (NAS, Plex, Home Assistant, etc.) use Dispatch to track maintenance schedules, configuration notes, and upgrade timelines. The Docker deployment fits naturally into existing docker-compose ecosystems, and the notes feature becomes living documentation.

3. Client Work Without Data Exposure

Freelancers handling sensitive client projects can deploy Dispatch on a VPS or home server, ensuring proprietary task details never sync to commercial productivity clouds. The project-based organization maps cleanly to client engagements.

4. Team Retrospectives and Sprint Planning

Small technical teams self-hosting Dispatch gain a Linear-like experience without per-seat pricing. The keyboard workflow keeps standups fast, while deadline focus prevents sprint scope creep. GitHub OAuth enables seamless team onboarding.

5. Personal Knowledge Management with Action Bias

Unlike Roam or Obsidian that optimize for note-taking over doing, Dispatch's integrated task-note-dispatch surface forces action. Notes without associated tasks become visible orphans, preventing the "beautiful second brain, zero output" trap.

Step-by-Step Installation & Setup Guide

Dispatch offers two deployment paths: Docker (recommended for production) and local Node.js development. Both are straightforward, but Docker eliminates environment variability.

Docker Setup (Production Recommended)

Prerequisites:

• Docker Desktop (Windows/macOS) or Docker Engine + Compose plugin (Linux)
• docker on your PATH with the daemon running
• Internet access to pull ghcr.io/nkasco/dispatchtodoapp:latest

Step 1: Clone and Launch

Windows PowerShell:

# Download the repository
git clone https://github.com/nkasco/DispatchTodoApp.git
cd DispatchTodoApp

# Run the automated setup script
.\dispatch.ps1 setup

Linux/macOS:

# Download the repository
git clone https://github.com/nkasco/DispatchTodoApp.git
cd DispatchTodoApp

# Make executable and run setup
chmod +x dispatch.sh
./dispatch.sh setup

The setup script automatically:

• Creates/updates .env.prod with your configuration
• Pulls the latest container image
• Configures volume mounts for SQLite persistence
• Starts the application stack

Step 2: Configure GitHub OAuth (Optional but Recommended)

During setup, when prompted:

Enable GitHub OAuth sign-in? [y/N]: y
AUTH_GITHUB_ID: your_oauth_app_client_id
AUTH_GITHUB_SECRET: your_oauth_app_client_secret
NEXTAUTH_URL: http://your-server-hostname:3000

Critical: For LAN or VPS deployments, use the actual server hostname or IP in NEXTAUTH_URL, not localhost. In your GitHub OAuth app settings, set:

Authorization callback URL: http://your-server:3000/api/auth/callback/github

Step 3: Verify Deployment

# Check running containers
docker ps | grep dispatch

# View logs
docker logs dispatchtodoapp

# Access the application
open http://your-server:3000

Your SQLite database persists in the mounted Docker volume or host path—surviving container restarts and updates.

Local Node.js Development Setup

Prerequisites:

• Node.js 20.9+ (LTS recommended)
• Git
• Platform build tools (if better-sqlite3 compilation fails):
  • Windows: Visual Studio Build Tools with C++ workload
  • macOS: xcode-select --install

Step 1: Install Dependencies

# Clone repository
git clone https://github.com/nkasco/DispatchTodoApp.git
cd DispatchTodoApp

# Install dependencies
npm install

Step 2: Environment Configuration

Create .env.local (distinct from Docker's .env.prod):

# Required: Random secret for NextAuth session encryption
AUTH_SECRET=$(openssl rand -base64 32)

# Required: Your development URL
NEXTAUTH_URL=http://localhost:3000

# Optional: GitHub OAuth for testing auth flows
AUTH_GITHUB_ID=your_github_oauth_client_id
AUTH_GITHUB_SECRET=your_github_oauth_client_secret

# Optional: SQLite database path (default: ./dispatch.db)
DATABASE_URL=./dispatch.db

Step 3: Database Migration

# Create tables and run migrations
npm run db:migrate

# Optional: Seed test account
npm run db:seed

Step 4: Start Development Server

# Starts both Next.js app (port 3000) and MCP server (port 3001)
npm run dev

Access at http://localhost:3000. The seeded account test@dispatch.local / test provides immediate access.

REAL Code Examples from the Repository

Let's examine actual implementation patterns from Dispatch's codebase and configuration.

Example 1: Docker Compose Production Configuration

The setup scripts generate a production-grade Docker Compose configuration. Here's the conceptual structure derived from the repository's deployment pattern:

# docker-compose.yml (implied from setup scripts)
version: '3.8'

services:
  dispatch:
    image: ghcr.io/nkasco/dispatchtodoapp:latest
    container_name: dispatchtodoapp
    ports:
      - "3000:3000"  # Next.js application
    environment:
      # Injected from .env.prod by setup script
      - AUTH_SECRET=${AUTH_SECRET}
      - NEXTAUTH_URL=${NEXTAUTH_URL}
      - AUTH_GITHUB_ID=${AUTH_GITHUB_ID}
      - AUTH_GITHUB_SECRET=${AUTH_GITHUB_SECRET}
      - DATABASE_URL=/data/dispatch.db  # Inside container path
    volumes:
      # CRITICAL: SQLite persistence across container restarts
      - dispatch-data:/data
      # Or bind mount for direct host access:
      # - ./dispatch.db:/data/dispatch.db
    restart: unless-stopped

volumes:
  dispatch-data:
    driver: local

Key insight: The volume mount is non-negotiable. Without it, your database evaporates on container recreation. The setup scripts handle this automatically, but understanding this pattern helps with custom deployments.

Example 2: Environment Configuration Pattern

The repository demonstrates clear separation between environments:

# .env.local — Local Node.js development ONLY
# ============================================

# NextAuth requires a secret for JWT encryption
# Generate with: openssl rand -base64 32
AUTH_SECRET=your_random_secret_here

# Must match your browser's access URL
# Use localhost for dev, actual hostname for LAN access
NEXTAUTH_URL=http://localhost:3000

# GitHub OAuth — optional but enables secure multi-user access
# Create at: https://github.com/settings/applications/new
AUTH_GITHUB_ID=Ov23lixxxxxxxxxxxx
AUTH_GITHUB_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# SQLite database location
# Relative paths resolve from project root
DATABASE_URL=./dispatch.db

Critical distinction: Docker uses .env.prod, Node.js uses .env.local. Never commit either—both contain secrets. The repository's .gitignore should exclude these (verify before contributing).

Example 3: Development Workflow Commands

The package.json scripts reveal the dual-service architecture:

{
  "scripts": {
    "dev": "concurrently \"next dev\" \"npm run mcp:dev\"",
    "build": "next build",
    "start": "next start",
    "db:migrate": "prisma migrate deploy",
    "db:seed": "tsx prisma/seed.ts",
    "mcp:dev": "tsx mcp-server/index.ts"
  }
}

When you run npm run dev, you're actually starting:

• Port 3000: Next.js application with React SSR
• Port 3001: Local MCP server for AI tool execution

This dual-port design is architecturally significant. The MCP server operates independently, meaning:

• AI tool calls execute through local infrastructure
• The Next.js app can restart without killing AI capabilities
• You could theoretically scale or modify either service independently

Example 4: Database Seeding for Development

The seed script creates predictable test data:

# After migration, create test account
npm run db:seed

# Outputs seeded credentials:
# Email: test@dispatch.local
# Password: test

This pattern enables immediate UI testing without OAuth configuration. In development, you can:

1. Reset database: rm dispatch.db && npm run db:migrate && npm run db:seed
2. Test authentication flows
3. Verify permission boundaries

Example 5: GitHub OAuth Callback Configuration

The README specifies precise callback URL formatting:

# GitHub OAuth App Settings → Authorization callback URL
# Pattern:  <NEXTAUTH_URL>/api/auth/callback/github
# Example:  http://dispatch-server.local:3000/api/auth/callback/github

# Common mistake — using localhost for LAN deployment:
WRONG:  http://localhost:3000/api/auth/callback/github
RIGHT:  http://192.168.1.50:3000/api/auth/callback/github

This tripped me up initially. NextAuth validates the callback URL against NEXTAUTH_URL. Mismatch causes cryptic "OAuth callback" errors. The setup script's interactive prompt helps prevent this, but manual Docker deployments require attention.

Advanced Usage & Best Practices

Backup Strategy for SQLite

Since your entire database is one file, backups are trivially simple:

# Automated daily backup via cron
0 2 * * * cp /path/to/dispatch.db /backups/dispatch-$(date +\%Y\%m\%d).db

# Pre-update snapshot before Docker image pulls
docker compose exec dispatch cp /data/dispatch.db /data/dispatch-pre-update.db

Reverse Proxy for HTTPS

Expose Dispatch through nginx or Traefik for TLS termination:

# nginx location block
location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    # Required for NextAuth session handling
    proxy_set_header X-Forwarded-Proto $scheme;
}

MCP Server Extension

The local MCP server on port 3001 accepts custom tools. Study mcp-server/index.ts to add integrations with your existing infrastructure—database queries, deployment triggers, or monitoring checks.

Performance Optimization

SQLite handles Dispatch's workload efficiently, but for larger deployments:

• Enable WAL mode for concurrent read performance
• Schedule VACUUM operations monthly
• Monitor database growth—notes with large Markdown can bloat file size

Comparison with Alternatives

Verdict: Choose Dispatch when data sovereignty, keyboard efficiency, and cost control outweigh the convenience of managed SaaS. The setup investment pays dividends in control and customization.

Frequently Asked Questions

Is DispatchTodoApp free to use?

Yes—completely open-source under standard OSS licensing. Self-hosting requires only your infrastructure costs. No feature gates, no "pro" tiers, no usage limits.

Can I use Dispatch without Docker?

Absolutely. The Node.js local development path supports full functionality. Docker simply simplifies deployment and dependency management.

How does Dispatch compare to Vikunja or other self-hosted todo apps?

Dispatch differentiates through its keyboard-centric design, integrated AI assistant with local MCP execution, and unified task-note-dispatch surface. Most alternatives focus narrowly on task lists without holistic productivity workflow.

Is my data secure if I expose Dispatch to the internet?

Enable GitHub OAuth, use HTTPS via reverse proxy, and consider VPN/network-level access controls. The codebase uses NextAuth.js for session security, but standard self-hosting security practices apply.

Can I migrate data from Notion or Todoist?

Currently no automated importer exists. The SQLite schema is straightforward—community contributions for migration scripts would be welcome. Export from other tools to Markdown/CSV, then script insertion.

What happens to the AI features without internet?

The MCP server architecture requires LLM API access (OpenAI, Anthropic, etc.), but tool execution stays local. For fully offline operation, the core task management functions normally—AI is optional enhancement.

Is Dispatch suitable for non-technical users?

The Docker deployment is approachable, but self-hosting inherently requires some technical comfort. For teams with mixed technical levels, consider pairing with a simple deployment platform like Coolify or Dokku.

Conclusion: Reclaim Your Productivity Stack

DispatchTodoApp represents something increasingly rare: a productivity tool built by developers, for developers, that respects both your workflow and your data. In an era where every SaaS product demands recurring rent for your own information, Dispatch's local-first SQLite architecture feels almost radical.

The keyboard-centric design isn't gimmickry—it's recognition that context switching kills flow. The integrated daily dispatch surface enforces action over accumulation. And the local MCP server for AI assistance proves that intelligent features don't require surrendering privacy.

Is it perfect? No. The setup requires more effort than signing into Notion. The ecosystem lacks the plugin breadth of Obsidian. But for developers who've felt the friction of tools built for spreadsheet jockeys rather than terminal dwellers, Dispatch is a revelation.

My recommendation: Deploy it this weekend. Run the Docker setup, seed the test account, and spend thirty minutes in the keyboard workflow. If you don't feel the difference in cognitive load, stick with your current stack. But I suspect you'll discover what the growing GitHub community already has: productivity tools don't need to live in someone else's cloud to be powerful.

Star DispatchTodoApp on GitHub • Pull the Docker image • Report issues and contribute

Your tasks. Your server. Your rules.