Self-hosted project management & issue-tracking solution + instant shareable & customizable boards + realtime collaboration, automation, API access and MCP-compatible client support

Table of contents

• Quick Start
  • Run the official Docker image
  • Run the Windows executable
  • Build locally from source
  • Run from source
• Optional Configuration
  • Environment variables
  • Encryption key (optional)
  • OIDC / SSO login (optional)
  • TLS / HTTPS (optional)
  • PWA / Web Push (optional)
  • Frontend build note
• Why Scrumboy?
• Who is this for?
• Modes
• Features
• Integrations & API Access
  • MCP (JSON-RPC) for AI agents
  • Webhooks (outbound HTTP)
• Config
• Roles
  • System roles (instance-wide)
  • Project roles (per project)
• Export scope
• Import modes
• Code layout (reference)
• 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.

Run the official Docker image

Scrumboy is distributed as a container image on GitHub Container Registry:

ghcr.io/markrai/scrumboy:latest

Docker run (named volume for persistent SQLite data under /data):

docker run -d \
  --name scrumboy \
  -p 127.0.0.1:8080:8080 \
  -v scrumboy-data:/data \
  ghcr.io/markrai/scrumboy:latest

The image defaults to DATA_DIR=/data and SQLITE_PATH=/data/app.db. Mount a volume or host directory on /data so the database survives container recreation.

Docker Compose (minimal example; save as docker-compose.yml):

services:
  scrumboy:
    image: ghcr.io/markrai/scrumboy:latest
    container_name: scrumboy
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./data:/data
    restart: unless-stopped

docker compose up -d

Open http://localhost:8080.

Run the Windows executable

Windows users can download scrumboy-*-windows-amd64.exe from GitHub Releases. The matching .sha256 file is published beside it for checksum verification.

Put the exe in a dedicated writable folder before running it, for example %USERPROFILE%\Scrumboy. The exe starts a local Scrumboy server; open http://localhost:8080 after it starts.

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. The exe is single-file for distribution, but it is not "no runtime files ever."

Advanced users can set DATA_DIR to choose the runtime data directory and BIND_ADDR to choose the listen address or port.

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.

Optional Configuration

Environment variables

• The app does not automatically load .env files.
• On Linux/macOS, export variables manually (for example: export SCRUMBOY_ENCRYPTION_KEY=...).
• On Windows, win_run_full.bat and win_run_anonymous.bat manage data/scrumboy.env automatically for local convenience.
• Precedence on Windows is: existing process env var SCRUMBOY_ENCRYPTION_KEY, then data/scrumboy.env, then legacy root scrumboy.env.
• The canonical Windows-managed local file format is SCRUMBOY_ENCRYPTION_KEY=<base64-32-byte-key>.
• Windows helper scripts still accept legacy raw single-line key files for backward compatibility.

Encryption key for 2FA/password reset

• SCRUMBOY_ENCRYPTION_KEY is not required for basic startup.
• It becomes required for encrypted auth/security features, including:
  • 2FA
  • Password reset flows
• If an existing database already has 2FA-enabled users, startup fails without this key.
• The key is part of the same backup/restore unit as data/app.db. Back them up together.
• Do not regenerate or replace the key casually after encrypted auth/security data exists, or you can break access to 2FA/password-reset data.
• If a bad key is configured before any encrypted auth/security data exists, Scrumboy may warn and continue with 2FA setup/password reset disabled until you configure a valid key.

Generate a key with: openssl rand -base64 32

Example for Docker Compose secret injection:

services:
  scrumboy:
    environment:
      - SCRUMBOY_ENCRYPTION_KEY=${SCRUMBOY_ENCRYPTION_KEY}

Example for systemd secret injection:

[Service]
Environment="SCRUMBOY_ENCRYPTION_KEY=REPLACE_WITH_BASE64_32_BYTE_KEY"

In both cases, the deployment manager is injecting the environment variable. Scrumboy itself does not auto-load these files.

OIDC / SSO login (optional)

Scrumboy supports OpenID Connect for single sign-on with any standards-compliant provider (Keycloak, Authentik, Auth0, Entra ID, etc.). OIDC is enabled by setting all four required environment variables:

Optional:

Local password authentication remains available by default alongside OIDC. After successful OIDC login, the user receives a standard Scrumboy session cookie. The IdP must return a verified email (email_verified: true). HTTPS is recommended when using OIDC to ensure session cookies are Secure.

See docs/oidc.md for full setup details, constraints, and troubleshooting.

TLS / HTTPS (optional)

• TLS is optional.
• HTTPS is enabled only when both SCRUMBOY_TLS_CERT and SCRUMBOY_TLS_KEY files exist.
• Otherwise, the server runs on HTTP by default.

PWA / Web Push (optional)

Install the app from the browser for a standalone window and better mobile UX. Background assignment alerts use the Web Push API with VAPID keys on the server. When both keys are set, signed-in clients attempt to subscribe automatically (browser permission may be prompted). Docker users must pass the VAPID variables into the container environment and recreate the container after changes. Details, Docker verification steps, and subscriber contact semantics: docs/pwa.md.

Frontend build note

The Docker image and go run embed prebuilt assets under internal/httpapi/web/dist. If they are missing, build them:

cd internal/httpapi/web
npm install
npm run build

Then run docker compose up --build (local image build) or go run ./cmd/scrumboy again from the repository root.

Why Scrumboy?

Simplicity of a light Kanban, with the power of structured systems: Roles, sprints, audit trails & customizable workflows - without being locked into SaaS tools.

Who is this for?

• self-hosted & privacy-focused community
• small to medium-sized teams & solo builders

Modes

• Full (SCRUMBOY_MODE=full, default): Auth can be enabled. First user via bootstrap; then login/session. Backup/export, tags, multi-project. Projects can be user-owned (project_members) or anonymous (shareable by URL): /anon (or /temp) creates a throwaway board and redirects to /{slug}.

• Anonymous (SCRUMBOY_MODE=anonymous): No auth. Landing at /; live deployment at: https://scrumboy.com/

Features

• Custom Workflows: You can create any combination of workflow you want, per project, with user-defined "Done" lane.

• 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: Search todos based on text or tags.

• Sprints: create, activate, close; sprint filter on board; default sprint weeks (1 or 2) per project.

• Authentication & 2FA: TOTP supported wh