Self-hosted project management & issue-tracking solution + instant shareable & customizable boards + realtime collaboration, automation, API access and MCP-compatible client support and zero SaaS lock-in
Table of contents
- Quick Start
- Features
- Modes
- Roles
- Optional Configuration
- Integrations & API Access
- Export scope
- Import modes
- Documentation
- License and Contributions
Quick Start
Runs in seconds. No setup required.
No .env file, TLS certificates, or encryption key are required to start the app.
Scrumboy creates runtime data under ./data by default. The default SQLite database is ./data/app.db, and SQLite may also create app.db-wal and app.db-shm while the server is running.
Run the official Docker image
Pull ghcr.io/markrai/scrumboy:latest (Docker selects the published architecture for your host):
docker run -d \
--name scrumboy \
-p 127.0.0.1:8080:8080 \
-v scrumboy-data:/data \
ghcr.io/markrai/scrumboy:latest
The mounted /data volume preserves Scrumboy data across container recreation. Open http://localhost:8080. For Compose using the published image, persistence, backup, and configuration details, see docs/docker.md.
Build locally from source
To build from a local clone instead of pulling the published image:
docker compose up --build
The repository's docker-compose.yml uses build: . and maps ./data to /data.
Open http://localhost:8080.
Run from source
go run ./cmd/scrumboy
Open http://localhost:8080.
Run the Windows executable
Windows users can download the windows-amd64 executable from GitHub Releases. Run it from a dedicated writable folder (for example %USERPROFILE%\Scrumboy); it starts a local Scrumboy server at http://localhost:8080. For exact artifact filenames, checksum and provenance verification, runtime-data location, and other release-install details, see docs/install-from-releases.md.
Run the macOS executable
macOS users can download Apple Silicon or Intel builds from GitHub Releases. These binaries require macOS 12 Monterey or later. Extract and run ./scrumboy from a dedicated writable folder; it starts a local Scrumboy server at http://localhost:8080. Current macOS release binaries are not Apple-signed or notarized. For exact artifact filenames, checksum and provenance verification, runtime-data location, Gatekeeper/quarantine troubleshooting, and other release-install details, see docs/install-from-releases.md.
Build the Android app
Scrumboy includes a native Android client, implemented with Capacitor, under mobile/capacitor. It connects to a running Scrumboy server; it does not replace or start the server. Build it from source. Release builds require HTTPS to that server. Prerequisites, web-payload packaging, Gradle commands, device connection, and optional signing are in docs/android.md.
Features
- Custom Workflows: You can create any combination of workflow you want, per project, with user-defined "Done" lane.
- Custom Priority Tiers: each project has ordered, color-coded priority definitions with stable keys; maintainers configure tiers and assign them to todos.
- Realtime SSE enabled boards for instant multi-user actions.
- Webhooks (API-only, full mode): Register URLs per project so Scrumboy can POST JSON when subscribed domain events fire (e.g.
todo.assigned). For your own automations, not in-app or browser notifications. See Integrations. - Customizable Tags: Users can inherit and customize tag colors.
- Advanced filtering: on desktop, the default compact Omni control shows recently active project tags when search is empty, narrows immediately to matching tag suggestions while typing, and provides arrows for paging the candidate shelf. Mobile retains its compact single rail for pinned tags and typed matches. Multiple pinned tags use logical AND and compose with ordinary text search, sprint, and other URL filters. The previous permanent tag/sprint pills remain available as Legacy pills under Settings → Customization.
- Sprints: create, activate, close; sprint filter on board; default sprint weeks (1 or 2) per project. Maintainers can disable sprints per project without deleting sprint history or todo assignments, then re-enable them later.
- Story archival: Archive and restore one story or a selection without touching workflow state or history - lane, rank,
doneAt, tags, links, sprint, priority and assignment are preserved, so metrics and sprint history are unaffected. Every board reader can browse the cursor-paginated Archive and inspect archived stories in a clearly marked read-only detail view; maintainers (and temporary-board capability holders) can restore or hard-delete them. Archived stories drop out of board, search and dashboard reads while still counting for integrity checks. The same single and atomic batch (1-500) operations are available over REST and MCP. Nothing is archived automatically. See API.md and docs/mcp.md. - Authentication & 2FA: TOTP supported when
SCRUMBOY_ENCRYPTION_KEYis set. - Self-service password reset email (optional, requires SMTP +
SCRUMBOY_ENCRYPTION_KEY+SCRUMBOY_PUBLIC_BASE_URL): see docs/smtp.md. - Audit trail: append-only
audit_eventstable; todo/member/project/link actions logged (see docs/audit-trail.md). - Backup: export/import JSON; merge or replace; scope full or single project. JSON export is not a complete
DATA_DIRdisaster-recovery backup (uploaded wallpapers andaudit_eventsare omitted); see docs/diagrams/scrumboy_deployment_ops.md. - Trello import: migrate an existing Trello board from its JSON export, with a preview before anything is imported (see docs/backup-and-import.md).
- Mobile: Native Android app (Capacitor client; build from source — docs/android.md) with native VoiceFlow on supported devices, or install the PWA from the browser.
- Multi-language Support: English, 简体中文, हिन्दी, Español (Latinoamérica), العربية, Français, বাংলা, Português (Brasil), Bahasa Indonesia, اردو, Русский, Deutsch, 日本語, Kiswahili, Tiếng Việt, Türkçe, 한국어, فارسی, ไทย, Italiano, Bahasa Melayu, Polski, and Українська.
- Anonymous shareable boards can be created in both Full & Anonymous deployments.
- VoiceFlow - deterministic voice commands in the browser; on supported Android devices, AI VoiceFlow adds on-device speech and Gemini Nano planning with confirmation before mutations (see docs/voiceflow.md, docs/enhanced-voiceflow.md).
- Sticky-Note Wall - per-project scratchpad of draggable sticky notes on the board (see docs/wall.md).
- Agenda - today's events from subscribed ICS feeds on durable boards (see docs/calendar.md). Requires
SCRUMBOY_ENCRYPTION_KEY. - Todo notes Markdown preview (optional) - markdown / preview tabs in the todo Notes field; optional Mermaid diagrams in fenced ````mermaid`blocks in preview only (see FAQ.md, docs/markdown-and-mermaid.md).
Modes
- Full (
SCRUMBOY_MODE=full, default): Auth can be enabled. First user via bootstrap; then login/session. Backup/export