Skip to content
Board Planner

Installing and running

Board Planner is self-hosted: one deployment is one instance, with its own database, users and projects.

What it needs

Section titled “What it needs”
  • Node.js and a package manager, to build and run the Next.js app.
  • MongoDB 4.4 or newer. The queries deliberately avoid operators introduced in 5.0, so 4.4 is genuinely supported.
  • Nothing else is required. AI, email and the PM agent are all optional and stay switched off until you configure them.

Configuration

Section titled “Configuration”

Everything is environment variables. Only the first one is required — without the rest, the features they belong to are simply absent from the interface rather than broken.

Variable Required What it does
MONGODB_URI Yes Connection string.
NEXT_PUBLIC_APP_URL No Public URL of the frontend, used to build links in notifications.
OPENAI_API_KEY No Turns on AI Assist in the task form. Without it the box is not rendered.
OPENROUTER_API_KEY No Turns on the PM agent. Without it the PM pages say so and stay inert.
PM_MODEL No Model for the PM agent. Defaults to moonshotai/kimi-k2.6.
PM_MAX_TOKENS No Output tokens per PM call. Default 8192.
PM_DAILY_TURN_CAP No PM turns per project per day. Default 100.
PM_SCHEDULER_TICK_MS No How often the autonomy scheduler wakes. Default 300000 (5 min).
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM No Email notifications. SMTP_PORT defaults to 587. Without these, notifications stay in-app.

Build and run

Section titled “Build and run”
Terminal window
npm install
npm run build
npm start

The MCP server that ships alongside the app builds separately, and is only needed for stdio clients — the HTTP endpoint at /api/mcp is part of the app itself:

Terminal window
cd mcp-server && npm install && npm run build

Deploying

Section titled “Deploying”

Any host that runs a Next.js app and can reach MongoDB will do. The reference deployment runs on Railway with auto-deploy from the main branch and MongoDB as a managed service on the same project, which keeps the database on a private network rather than the public internet.

Whichever host you pick, set NEXT_PUBLIC_APP_URL to the public URL — notification links are built from it, and they are wrong or missing without it.

The first account

Section titled “The first account”

The instance needs one administrator before anyone can sign in. Once that account exists, every other account is created from Settings → Users — there is no open sign-up to leave switched on by accident.

After it is up

Section titled “After it is up”
  1. Create your first project and adjust its columns — see Board columns and task fields.
  2. Add the rest of the team and grant project access — see Members and permissions.
  3. Issue an API token if an agent will be working the board — see Claude Code and MCP.