Getting started

Installation

Brigade is one binary, brigade. Use the one-line installer (it sets up Node for you) or install from npm if you are already on Node 22.12+. The first launch walks you through a short setup wizard — storage, a model provider, and web search.

Requirements#

Install#

Fastest — handles Node for you

One line. The installer puts Node 22.12+ on the machine if you don't already have it, then installs Brigade:

# macOS / Linux$ curl -fsSL https://brigade.spinabot.com/install.sh | sh

irm https://brigade.spinabot.com/install.ps1 | iex

Already on Node 22.12+?

Install straight from npm so the brigade command is on your PATH:

$ npm i -g @spinabot/brigade

Confirm it is installed:

$ brigade --version

Don’t have Node or npm?#

The one-line installer above handles this for you — this section is for the npm route, or if you would rather put Node on the machine yourself. npm ships inside Node.js; it is not a separate download. So if a machine has no Node, it has no npm either, and npm i @spinabot/brigade has nothing to run from: something has to put Node on the machine first. The good news is that Node is the only prerequisite, and getting it is a one-time, one-line step.

Get Node first (the one prerequisite)

Install Node 22.12 or newer using whichever of these fits your setup, then come back and run the install command above:

# macOS / Linux — via nvm (https://github.com/nvm-sh/nvm)$ nvm install 22 # macOS / Linux — via fnm (https://github.com/Schniz/fnm)$ fnm install 22 # Windows — via winget$ winget install OpenJS.NodeJS.LTS

Prefer a graphical installer? Download the LTS build straight from nodejs.org — it bundles npm, so once it finishes you can run npm i -g @spinabot/brigade right away.

Already have Node, just an old one?

Brigade checks for you. Every launch verifies your Node version against the 22.12 minimum (also declared in the package’s engines field), and if it is too old it stops with an actionable message that tells you exactly how to upgrade — for example nvm install 22 — instead of failing with a cryptic stack trace. Nothing installs a new runtime behind your back; you stay in control of what lands on your machine.

First launch#

Run brigade onboard (or just brigade, which runs onboarding on the very first launch). The wizard walks you through five steps:

1. 1

   Choose a storage mode

   Filesystem (the default — everything under ~/.brigade/) or a fully self-hosted Convex backend. See Storage.
2. 2

   Pick a provider

   Choose from Anthropic, OpenAI, Gemini, OpenRouter, Ollama, and more.
3. 3

   Connect it

   Paste an API key — validated live — or connect your local Ollama install.
4. 4

   Choose a default model

   Pick the model new sessions start on. You can switch any time with /model.
5. 5

   Pick web search

   Choose a search backend; keyless options (DuckDuckGo, Wikipedia, and more) work out of the box. See Models & web search.

Subsequent launches resume right where you left off. You can re-run the wizard any time with brigade onboard.

$ brigade onboard    # the five-step setup wizard$ brigade            # chat TUI (auto-starts the gateway if needed)

Verify your install#

brigade doctor health-checks your Node version, your ~/.brigade/ directory, config, configured providers, the log sink, prompt files, and — optionally — a running gateway. It exits 0 on pass and 1 on failure, so it is safe to wire into CI.

$ brigade doctor$ brigade doctor --json      # machine-readable$ brigade doctor --strict    # exit 1 on warnings too

Run from source#

Prefer to build from a checkout? Clone the repo and build. The npm scripts wrap the binary so you do not have to type node:

$ git clone https://github.com/spinabot/brigade.git$ cd brigade$ npm install$ npm run build      # tsc → dist/$ npm run dev        # rebuilds dist/ if src/ changed, then runs$ npm link           # make the global `brigade` point at this checkout

From inside the checkout, npm-script shortcuts wrap the same commands (so you never type node) — the simplest way to run from source:

$ npm run onboard      # = brigade onboard   (provider/model wizard)$ npm run tui          # = brigade           (the chat TUI)$ npm run gateway      # = brigade gateway run    (also gateway:status / gateway:stop)$ npm run connect      # = brigade connect$ npm run status       # = brigade status         (status:json)$ npm run doctor       # = brigade doctor         (doctor:json / doctor:strict)