Skip to content
Get packs

Guide · Open source

How to use Brigade: install, run your AI crew and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

Brigade is an open-source, self-hosted system for running a team of AI agents that share one long-term memory called Tideline. This guide shows you how to install it, start a first chat, and understand the main pieces so you can decide whether it fits your setup. You will need to be comfortable running a command in a terminal.

Brigadespinabot/brigade · ★ 11.4k · MIT

Quick start

  1. 1Check Node.js. Confirm you have Node.js 22.12 or newer, or plan to use the install script which installs Node if needed.
  2. 2Install Brigade. Run the install script for macOS or Linux, the PowerShell script on Windows, or npm i -g @spinabot/brigade if Node is already set up.
  3. 3Start the chat. Run brigade in your terminal to open the chat TUI.
  4. 4Connect a model. Sign in with a supported subscription or add a provider key, or point Brigade at a local Ollama model.
  5. 5Add channels or agents. Connect a messaging channel such as Telegram or Slack, or create isolated agents for your crew.
  6. 6Keep your data. Check ~/.brigade/ regularly and back it up before major changes.

Check what you need before installing Brigade

Brigade is installed with a package manager. The prerequisite is Node.js 22.12 or newer. If you do not have Node, the install script installs it for you.

Brigade stores its files in a single directory, ~/.brigade/, and keeps your keys on your own machine. Plan for a laptop or a server you control.

  • Node.js 22.12+ (or use the install script, which installs Node if needed)
  • A terminal and comfort with command-line installs
  • Space for a local directory under ~/.brigade/

Install Brigade on macOS, Linux or Windows

On macOS or Linux, the install script installs Node if needed, then Brigade, without sudo. On Windows, use the PowerShell script. If Node 22.12+ is already installed, you can install straight from npm.

If you see EACCES or permission denied, do not use sudo. The source recommends either the curl install script or fixing your Node global folder permissions.

  • macOS / Linux: run the install script, then brigade
  • Windows: run the PowerShell install script
  • Already on Node 22.12+: install via npm
curl -fsSL https://brigade.spinabot.com/install.sh | sh brigade

Start your first chat with the brigade command

Running brigade opens a fast chat TUI in your terminal. This is the simplest way to start. The README describes the terminal as flicker-free and says there is no browser and no Electron.

Brigade's other commands include brigade mcp for exposing long-term memory to MCP clients, and brigade expose for sharing a local port over HTTPS.

  • brigade opens the chat TUI
  • brigade mcp exposes long-term memory to any MCP client
  • brigade expose and brigade expose stop manage the tunnel
npm i -g @spinabot/brigade

Connect a model provider or a local Ollama model

Brigade can use many providers, including Anthropic, OpenAI, Gemini, Groq and local Ollama, or any OpenAI-compatible endpoint. You can switch models mid-conversation. If you already have a Claude, ChatGPT or Copilot subscription, the README says you can sign in with it instead of managing API keys.

Keys are stored locally at mode 0600, so you do not need to hand them to a middleman.

  • Use a Claude, ChatGPT or Copilot subscription sign-in instead of an API key
  • Use a local Ollama model if you want data to stay on your machine
  • Switch models mid-conversation

Add channels, agents and memory

Once the basics work, you can reach your crew from WhatsApp, Telegram, Slack, Discord, iMessage and BlueBubbles. Brigade can run isolated agents with their own workspaces and credentials, and wire them into an org chart that controls who can talk to whom.

Tideline is the long-term memory shared by the crew. Facts persist across sessions, with origin scoping, decay and hybrid keyword and vector recall. Privileged actions wait for your approval.

  • Channels: WhatsApp, Telegram, Slack, Discord, iMessage, BlueBubbles
  • Team Mode and an org chart for delegation
  • Cron scheduler and sub-agent fan-out
  • Built-in Composio tool for 1,000+ app connectors

Back up, reset or remove Brigade

Everything lives under ~/.brigade/, which you fully own. The README notes that removing that directory wipes Brigade clean. Storage is filesystem by default, with an optional self-hosted Convex backend.

Back up that directory before major changes if you want to keep your memory and agents.

  • Default storage: filesystem under ~/.brigade/
  • Optional storage: self-hosted Convex with at-rest encryption
  • Reset: removing ~/.brigade deletes its data
rm -rf ~/.brigade

What people use it for

  • Run a personal multi-agent assistant on a laptop that keeps keys and data local
  • Reach your agents from Telegram, Slack or Discord while the server stays under your control
  • Delegate tasks between agents organised in an org chart
  • Let an assistant read documents and create Word, Excel or PDF files, as the README describes

Frequently asked questions

Is Brigade free and open source?

Brigade is released under the MIT licence, according to its repository. The source describes it as a self-hosted ecosystem with no account and no SaaS in the middle. Check the repository licence file for the exact terms.

What do I need to install Brigade?

You need Node.js 22.12 or newer, or you can use the install script, which installs Node if needed. The source says installation is done from the terminal and that everything lives under ~/.brigade/.

Can Brigade run with Ollama locally?

Yes. The README says Brigade can use local Ollama models and keeps your keys and data on your own machine. Choose an Ollama model as your provider inside Brigade.

Do I need an API key to use Brigade?

Not necessarily. The README says you can sign in with a Claude, ChatGPT or Copilot subscription, or reuse a login from the Claude Code or Codex CLI.

How does Brigade compare to CrewAI or AutoGPT?

This analysis lists AutoGPT, CrewAI, LangGraph and OpenHands as comparable projects. Brigade's distinguishing features in the source are the Tideline shared memory, the org chart and self-hosting with messaging channels. This guide did not benchmark them against each other.

Where is my data stored and how do I remove it?

Data lives under ~/.brigade/. Keys are stored locally at mode 0600. Running rm -rf ~/.brigade removes it, as the README describes.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Brigade suits developers and privacy-minded users who are comfortable with a command-line install and want to host their own multi-agent setup on hardware they control. If you want a polished consumer app with no setup, or you need a verified security review, pick a different tool; this analysis did not verify the security claims in the README.

Install options & downloads