Quickstart

Bring the whole stack up with Docker, then log in with the seeded demo account. You only need Docker and about a minute.

Run the stack

git clone https://github.com/0-to-1-Labs/tracker.git
cd tracker
cp .env.example .env          # set SESSION_SECRET for anything non-local
docker compose up             # builds + runs web + api + mcp + postgres + redis

docker compose up builds and starts every service. The api applies its database migrations on start (idempotent), then serves.

Service	URL	What it is
Web SPA	http://localhost:8080	The React board UI
API	http://localhost:3000	REST under /api, WS at /ws, GET /health, GET /openapi.json
MCP	http://localhost:3001	Standalone MCP server — GET /health, POST /mcp

The web container (nginx) serves the SPA build and reverse-proxies /api and the /ws upgrade to the api.

SESSION_SECRET

docker compose up refuses to start without SESSION_SECRET. Generate one:

openssl rand -hex 32

Put it in .env. See Configuration for every setting.

Seed a demo login

Seed a known human login, a demo board, and a demo agent token (idempotent — safe to re-run):

pnpm --filter @kanban/api db:seed

This creates:

• a human login — demo@kanban.local / demo1234
• a "Demo Board" with To Do / In Progress / Done and a few cards
• a demo agent actor plus a freshly-minted Bearer token, printed once

Open http://localhost:8080 and sign in with the demo credentials, or register a fresh account from the SPA.

Try it as an agent

The seed prints a Bearer token for the demo agent. Point it at the api:

export TOKEN=kbt_...        # copy from the seed output
curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/boards

That is the whole agent on-ramp — the Agent quickstart takes it from here (create a card, connect over MCP, drive a work session).

Local development (api/web outside Docker)

Prefer to run the app processes directly against the compose backing services?

pnpm install
docker compose up -d postgres redis     # just Postgres + Redis
cp .env.example .env                     # DATABASE_URL / REDIS_URL / SESSION_SECRET / PORT

pnpm --filter @kanban/api exec drizzle-kit migrate   # apply migrations
pnpm --filter @kanban/api dev            # api on :3000
pnpm --filter @kanban/web dev            # SPA on :5173 (proxies /api + /ws → :3000)

Next steps

• Self-hosting — run it in production behind TLS.
• User guide — boards, fields, search, automations.
• Agents — the actor model and how agents drive a board.