Skip to main content

Installation

Two ways to install​

Option A — Desktop app (recommended)​

Download the pre-built installer from GitHub Releases:

  • macOS: Squadboard-*.dmg (Intel + Apple Silicon)
  • Windows: Squadboard-Setup-*.exe
  • Linux: Squadboard-*.AppImage

Install and run — no Node.js required, no Docker, no config.

Option B — npm CLI​

npx @sabbour/squadboard-cli init

Requirements: Node.js 20 or newer, pnpm 8 or newer

This scaffolds a local project and starts the dev server at http://localhost:5173.

Start the app​

If you installed via npm:

pnpm run dev

This starts the Express/WebSocket backend and the React/Vite frontend. The frontend loads at http://localhost:5173.

Squad state uses PostgreSQL by default. Existing .squad/ files are imported once into an empty DB-backed project. Use pnpm run dev:fs if you intentionally want repository .squad/ files to remain the live state store.

Start the docs site​

pnpm docs:dev

The Docusaurus site is mounted with baseUrl: /docs/, so local links match the production shape used by the hosted docs.

Production builds​

Build everything:

pnpm build

Build only the docs site:

pnpm docs:build

Serve the built docs:

pnpm docs:serve

Wire up MCP (Copilot CLI integration)​

To let Copilot CLI and agents use Squadboard tools, wire up the MCP connection:

npx @sabbour/squadboard-cli connect

This writes .copilot/mcp-config.json into your Squad project and injects squad.agent.md hints so agents know how to invoke Squadboard tools. Safe to re-run.

For diagnostics, check that the connection is healthy:

npx @sabbour/squadboard-cli diagnose

This prints a table: server reachability, MCP config presence, squad.agent.md injection status, and Electron binary location.

Manual MCP setup (if you prefer): Write .copilot/mcp-config.json directly:

{
  "mcpServers": {
    "squadboard": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Use an external Postgres (optional)​

For team state or persistence across restarts:

DATABASE_URL=postgresql://user:pass@host:5432/squadboard pnpm run dev

Next steps​

Last updated on