Brigade: a self-hosted crew of AI agents on one machine

The problem Brigade targets: one owner, many agents, no SaaS in the middle

Most agent tooling assumes a single assistant in a browser tab. Brigade assumes the opposite: a crew. The README describes "a crew of AI agents on a real org chart that share one long-term memory, Tideline, so what one agent learns, the rest can use." The intended user is someone who already runs a server or a Raspberry Pi and wants agents with separate credentials and workspaces rather than one shared context window.

The sovereignty claim is the differentiator. According to the README, there is no account to create and no SaaS in the middle; API keys stay on the machine and the project states it sends no telemetry. That matters if your agents touch private repositories or internal documents, because the usual alternative is routing every prompt through someone else's hosted control plane.

The second problem is continuity. A chat session that forgets everything on restart is not useful for recurring work. Brigade's Tideline engine is described as persisting facts across sessions with origin scoping, decay, and hybrid keyword plus vector recall. Whether that recall quality holds up is not something the README quantifies.

How Brigade works: a state directory, an org chart, and two storage modes

Everything lives under one directory, ~/.brigade by default, which the README calls a directory "you fully own." That directory holds config, agents, sessions and logs. The environment example file confirms the layout: BRIGADE_STATE_DIR overrides the location, BRIGADE_CONFIG_PATH points at a specific brigade.json, and BRIGADE_PROFILE switches the default agent's workspace to a named profile directory. Per-agent workspaces are unaffected by the profile setting, since each agent always gets its own directory under agents/<id>/.

Storage is the main architectural fork. BRIGADE_MODE takes either filesystem (the default) or convex, and when set to convex you also set BRIGADE_CONVEX_URL. The example file is explicit that the mode "is resolved at boot from a sticky sentinel and freezes for the process," so changing it requires a gateway restart. There is also a documented escape hatch for running a filesystem command against a convex sentinel, described as one-shot diagnostics only.

Above storage sits the coordination layer. Agents are wired into an org chart that, in the README's words, "governs who can" delegate to whom. Sub-agent fan-out and a cron scheduler sit alongside it. The README does not publish the delegation semantics in detail, so the practical way to learn the hierarchy rules is the source tree, particularly src/ and the COMMANDS.md file at the repository root.

Installing Brigade and running a first crew

The README gives a single install line for macOS and Linux. It installs Node if needed, then Brigade, and the comment states it does not use sudo.

# macOS / Linux — installs Node if needed, then Brigade (no sudo)
curl -fsSL https://brigade.spinabot.com/install.sh | sh
brigade

Running brigade with no arguments starts a chat TUI. The README describes it as flicker-free and terminal-first, with no browser and no Electron. That is the first thing you should see: a prompt, not a web page.

The npm package is @spinabot/brigade, so an npm install is the other route the repository implies through its package metadata. The README does not spell out an npm-based install sequence, so treat the shell script as the documented path.

Configuration is optional. The .env.example file states every entry is optional and that Brigade boots with sensible defaults when nothing is set. Copy it to .env and uncomment only what you need:

cp .env.example .env
# then edit .env and uncomment only the lines you want

The file also notes a stale or absent .env is safe, because Brigade reads the live process environment rather than the file itself. If you want a different state location, set BRIGADE_STATE_DIR before the first run rather than moving ~/.brigade afterwards.

Providers, subscriptions, and the no-API-key path

Brigade does not lock you to one model vendor. The README lists Claude, GPT, Gemini, Llama, and a local Ollama as options, and states that agents can switch models mid-task without losing the thread.

The more unusual claim is credential reuse. The README says you can sign in with a Claude, ChatGPT, or Copilot subscription, or reuse an existing Claude Code or Codex CLI login with no browser and no re-auth. If that works as described, it removes the most common friction point in self-hosted agent setups, which is provisioning and rotating API keys. The README does not explain how the reuse is implemented, so the mechanism is not something you can audit from the documentation alone.

There is a second exposure path worth noting. Brigade ships an expose command, with the README also documenting the alias brigade bloody benchmark, which tunnels a running crew to the public internet. The README says HTTPS terminates at the edge, defaults to Cloudflare, and supports bringing your own relay via bore, frp, or sish. A secret key rides along invisibly, and unauthorized requests get a 401. The stop command is brigade expose stop. Exposing agents that can act in a thousand apps is a deliberate risk, and the README frames it as a stress test rather than a production feature.

Where Brigade gets thin: docs that promise more than they specify

The README is long on capability and short on failure modes. That imbalance is the main thing to weigh before adopting.

Consider the storage switch. The example file says the mode freezes for the process and needs a gateway restart, but nothing in the repository documentation describes migrating existing filesystem data into Convex, or what happens to sessions and memory when you switch. A sticky sentinel that refuses mismatched commands is a safety feature, and it is also a trap if you do not know how to clear it. The README does not document rollback.

The connector count is another gap. The README says agents act inside "1,000+ apps you already use" and mentions 1,000+ app connectors, but it does not list them, does not describe the authentication model per connector, and does not say what happens when a connector's upstream API changes. For an agent with write access to your calendar or issue tracker, that omission matters more than the headline number.

The privilege model is described at a high level: privileged actions wait for your approval. There is no published approval taxonomy in the README, so you cannot tell which actions count as privileged. SECURITY.md exists at the repository root and is the right place to look, but the README does not summarize it.

Finally, the README leans on marketing language in places, including a benchmark framing built around strangers poking your agents. That is a stylistic choice, and it also means the project's own prose is not a reliable proxy for what is tested.

Brigade compared with single-agent CLI tools

The closest comparison is a single-agent coding CLI such as Claude Code or Codex, both of which Brigade explicitly interoperates with for login reuse. The difference is scope. A coding CLI is one agent in one working directory with one conversation. Brigade is many agents with separate workspaces and credentials, a shared memory layer, an org chart for delegation, a cron scheduler, and messaging channels including WhatsApp, Telegram, Slack, Discord, iMessage, and BlueBubbles.

That is a real architectural difference, not a packaging one. Shared memory across agents means a fact learned by one agent can be recalled by another, which a per-session CLI cannot do without you pasting context. The org chart means delegation is governed rather than ad hoc.

The cost is operational surface. A coding CLI is a process you start and stop. Brigade is a runtime with a state directory, a storage mode you can freeze by accident, a gateway that needs restarting, an optional database you may have to operate, and an expose command that can put agents on the public internet. If your work is one developer editing one repository, the crew model adds moving parts you will not use.

Maintenance, licence, and what a Brigade upgrade actually costs you

Brigade is not archived. The most recent release is brigade-v1.37.1, dated 2026-09-09, with v1.37.0 a week earlier and v1.36.1 two days before that. The cadence is fast, and the repository uses release-please, visible in .release-please-manifest.json and release-please-config.json at the root. Note that package.json carries version 1.38.0 while the newest listed release is 1.37.1, which suggests the npm package can move ahead of the tagged release.

Fast releases mean upgrade cost is real. Brigade is installed as a global binary, keeps state in ~/.brigade, and can hold a Convex backend. The example file warns that storage mode is sticky and frozen per process, so an upgrade that changes mode handling is the kind of thing that can require manual intervention. Before upgrading, check CHANGELOG.md rather than the README, since the README is not versioned per release.

The licence is MIT, stated in package.json and in the LICENSE file. MIT permits commercial use, modification, and redistribution with the copyright notice preserved. It offers no patent grant and no warranty, which is the standard trade-off for permissive licences. This is a description of the licence text, not legal advice; if you are embedding Brigade in a product, have counsel read the actual LICENSE file.

One practical note on the install path: the documented install runs a remote shell script through curl. That is a supply-chain surface you are choosing to trust. The npm package at @spinabot/brigade is the alternative if you prefer a registry-mediated install.

Editorial conclusion

Adopt Brigade if you want a crew of agents with shared memory on hardware you own and you are willing to read the source when the docs thin out. Do not adopt it if you need a documented rollback path, a Convex migration plan, or a vetted security posture; the README covers none of those. Before committing, verify on a scratch machine that ~/.brigade can be deleted and recreated cleanly, and check whether the Convex backend is something you want to operate.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. spinabot/brigade on GitHub