Quick Start

Runs in seconds. No setup required.

No .env file, TLS certificates, or encryption key are required to start the app.

Run with Docker

docker compose up --build

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.

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:

| Variable | Description | |----------|-------------| | SCRUMBOY_OIDC_ISSUER | Issuer URL (e.g. https://auth.example.com/realms/main) | | SCRUMBOY_OIDC_CLIENT_ID | OAuth client ID | | SCRUMBOY_OIDC_CLIENT_SECRET | Confidential client secret | | SCRUMBOY_OIDC_REDIRECT_URL | Full callback URL registered at IdP (e.g. https://scrumboy.example.com/api/auth/oidc/callback) |

Optional:

| Variable | Description | |----------|-------------| | SCRUMBOY_OIDC_LOCAL_AUTH_DISABLED | Set to true to disable local password login when OIDC is configured (SSO-only mode) |

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). Details 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 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 when SCRUMBOY_ENCRYPTION_KEY is set.

• Audit trail: append-only audit_events table; todo/member/project/link actions logged (see docs/AUDIT_TRAIL.md).

• Backup: export/import JSON; merge or replace; scope full or single project (see store backup logic).

• PWA: Excellent UX for mobile users.

• Anonymous shareable boards can be created in both Full & Anonymous deployments.

• VoiceFlow - deterministic voice commands (see docs/VOICEFLOW.md).

• Sticky-Note Wall - per-project scratchpad of draggable sticky notes on the board (see docs/WALL.md).

• Todo notes Markdown preview - markdown/preview tabs in the todo Notes field (see FAQ.md, docs/markdown.md).

Integrations & API Access

Scrumboy supports API access tokens for automation, integrations, and programmatic MCP access (legacy HTTP and JSON-RPC - see below). Full MCP guide for developers and agents: docs/mcp.md.

You can create a token from the API and use it to call MCP endpoints directly - no browser session or cookies required.

Create a token (requires login session):

curl -b cookies.txt -X POST http://localhost:8080/api/me/tokens \
  -H "Content-Type: application/json" \
  -H "X-Scrumboy: 1" \
  -d '{"name":"cli"}'

Response includes a one-time token (starts with sb_).

Use it with MCP:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sb_your_token_here" \
  -d '{"tool":"projects.list","input":{}}'

MCP (JSON-RPC) for AI agents

Scrumboy exposes a Model Context Protocol (MCP) compatible JSON-RPC endpoint for AI agents (Claude, etc.) and MCP-compatible clients.

Endpoint: POST /mcp/rpc

This is separate from the /mcp HTTP endpoint above and follows JSON-RPC 2.0 (initialize, tools/list, tools/call, etc.). See docs/mcp.md for tools, auth, response shapes, and examples; API.md for the full HTTP/MCP behavior reference.

Example: initialize

curl -X POST http://localhost:8080/mcp/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Example: list tools

curl -X POST http://localhost:8080/mcp/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Example: call a tool

curl -X POST http://localhost:8080/mcp/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sb_your_token_here" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"todos.create",