Docs / Self-hosting
Run the backend
The backend holds shared memory and claims across your machines. What it collects, which setup to choose, and why it stays on a private network.
The backend is what holds shared memory and repository claims across your machines. The commands and config call it Fleet Hub, so that is the name you will see in brigadestack fleet output and in fleet.toml. Run it on the same machine when you work alone, or on a shared server when several machines or people work together. Each machine keeps its own run journal and reports events to the hub, so one place shows what is running where, which agent tool is running it, and who holds a claim on a repository. The hub keeps its state in a SQLite database on local disk. With shared memory on, cards go in a second database file beside it, fleet-hub-memory.db, and the brigade-hub front process answers the memory routes and starts the Python hub behind it.
The hub includes a Dashboard. Its pages group into Overview, Work, Capacity, Projects and Settings. Repositories is a page under Projects. Agents and commands do not depend on it.
In current releases the CLI still runs when no hub is configured, and the guides below set up a shared server. If the hub goes down, machines keep writing their journals, hold their reports in a local spool, and send them in order when it returns. The hub ignores a repeated event, so a resend is safe. Model admission that depends on the hub can still refuse a launch during an outage.
Set up with your agent
What each machine sends
Each machine’s run journal under .brigade/runs/<run>/events/ is the source of truth for that machine. The hub is an aggregate view and a claim arbiter. Repositories, handoffs and check records live on the machine, and the node token is a file only that machine’s user can read.
The hub receives:
- One event for each journal append.
- Repository claims.
- A SHA-256 of each node token at enrollment. The hub does not store the token itself.
An event names the node, run, repository, seat, harness and state, with a timestamp, a sequence number and a digest. The hub drops a repeat of the same (node_id, run_id, sequence, digest).
Choose a setup
| Setup | Status | Pick it when |
|---|---|---|
| Proxmox LXC | Recorded runbook, runs under systemd | You have a Proxmox VE 9.x host and want a small dedicated container |
| Docker or Podman | Preview | A host already runs containers and you want Compose or a rootless Podman Quadlet |
Both released setups run one hub replica with its database on a local disk, reachable over plain HTTP only on the host’s loopback address.
Keep the hub on a private network
Put the hub on a private network such as a tailnet. Bind it to loopback and let a local proxy such as Tailscale Serve be the only way in. Do not bind it to all interfaces, and do not publish it through a public tunnel. The same rule holds for Cloudflare Tunnel: do not publish the backend or any local queue path.
Clients refuse a remote hub URL that is plain HTTP, so give them the HTTPS origin the proxy serves.
Two kinds of token
- Node token. One per machine. It is that machine’s identity: the hub reads the
node_idfrom it and refuses an event or claim for any other node with HTTP 403. - Admin token. The control plane. It enrolls nodes, reads status and claims, and mints dashboard enrollment codes. Keep it on the hub and on the operator machine that enrolls nodes. A node does not need it.
Create tokens on the hub host or the operator machine. Store each one in a file only its user can read, with mode 0600. Do not put a token in a command line, a chat, or a file that git tracks.
Enroll a machine
Every machine that reports needs its own node token. The short version, from the operator machine that holds the admin token:
brigadestack node --machine --json
brigadestack fleet nodes add <NODE_ID> --label <HOSTNAME>
brigadestack fleet status
The first command runs on the new machine and prints its node_id. The second prints the node token once, and the hub keeps only its hash. Deliver that token to the machine, point ~/.brigade/fleet.toml at it, and the machine starts reporting. Step 7 of the Proxmox guide has the full steps, including Windows. They apply to every setup.
Turn on shared memory
A plain brigadestack fleet serve tracks runs and claims but has no memory API. Shared memory needs the brigade-hub component and one extra flag. The component is Linux only.
brigade-hub is a Rust engine that runs in front of the Python backend. It answers the route families you set to native and forwards the rest to Python. Without --route-mode it answers only health and metrics itself, and a forwarded request takes longer through it than from Python directly. A plain fleet serve runs Python alone: the Rust engine is optional, Linux only, and not the default.
With heartbeats served natively, it handled 13 to 47 times as many heartbeat writes per second as Python in our benchmarks:
| Clients | Rust, OK writes/s | Python, OK writes/s | Ratio |
|---|---|---|---|
| 16 | 2,562 to 2,936 | 189 to 194 | 13.6x to 15.1x |
| 32, on 1 vCPU and 512 MiB | 3,486 to 4,433 | 195 to 200 | 17.9x to 22.1x |
| 64 | 8,845 to 10,224 | 225 to 229 | 39x to 45x |
| 64, mixed with other work | 8,815 to 9,131 | 187 to 205 | 45x to 47x |
| 256 | 6,709 to 6,931 | 229 | 29x to 30x |
Each row is two 30-second runs after a 5-second warmup, with FULL durability on both engines, on an Intel Core Ultra 9 285 on 2026-11-17. At 256 clients Rust refused no connections and had no transport errors, and its highest p99 latency in any row was 93 ms. An earlier run on 2026-11-05 measured 31 times at the 32-client, 1 vCPU setting (engines/hub/bench/S6.md). The new run was on btrfs and the earlier one on ext4, and that difference is under investigation, so treat all of these numbers as provisional. Add --route-mode heartbeat=native to serve heartbeats from Rust.
1. Install the component on the backend host:
brigadestack setup --component brigade-hub
setup downloads the binary that matches your release. If you build brigade-hub from source instead, pass --hub-binary <path> and --hub-sha256 <digest> to fleet serve. The backend refuses a binary that its group or other users can write.
2. Start the backend with memory on. Add two flags to the fleet serve command your setup guide uses:
brigadestack fleet serve --engine rust --route-mode memory=native \
--host 127.0.0.1 --port 40657 --token-file ~/.brigade/admin-token --db ~/.brigade/fleet-hub.db
Without --route-mode memory=native the memory routes answer not found. The default port is 3774. The sample output below uses 40657.
The token file must exist before you start the backend. The block below creates it.
On one machine. If you work alone, one machine can be the backend and its only client. Create the admin token file with a private mode:
umask 077
openssl rand -hex 24 > ~/.brigade/admin-token
Start the backend with the command from step 2. Then write ~/.brigade/fleet.toml so the CLI knows where it is:
[fleet]
hub_url = "http://127.0.0.1:40657"
token_file = "~/.brigade/admin-token"
Enroll this machine and keep its node token. The token is the last line of the output and is shown once:
brigadestack fleet nodes add "$(brigadestack node --machine | sed -n "s/^node_id: //p")" --label laptop | tail -n 1 > ~/.brigade/node-token
echo 'node_token_file = "~/.brigade/node-token"' >> ~/.brigade/fleet.toml
3. Point a repo at it. On an enrolled machine (see Enroll a machine), add a [hub] table to the repo’s .brigade/memory-care.toml:
[hub]
mode = "sync"
scope = "repo:me/my-app"
read_scopes = ["repo:me/my-app"]
Then check that the backend answers:
brigadestack memory hub status --target .
memory hub: mode sync, scope repo:me/my-app
hub url: http://127.0.0.1:40657 (source: fleet)
hub: 0 card(s), seq 0, indexed 0, retrieval lexical, as 3f77d578-6529-45bd-a5ef-c23faeab6c2a
4. Publish the cards you have. In 0.31.0 this is a command, not a scheduled job:
brigadestack memory hub push --target . --yes
memory hub push: 1 published, 0 spooled, 0 proposal(s), 0 refused, 0 kept local, 0 skipped, 0 derived id(s)
5. Read them somewhere else. In a second checkout or on another enrolled machine, a read-only [hub] table is enough. A fresh clone needs brigadestack init first, because .brigade/ is gitignored. The recorded session ran brigadestack init --target ~/my-app-b --depth repo --harnesses codex. Then add:
[hub]
mode = "read"
read_scopes = ["repo:me/my-app"]
brigadestack memory search "fake clock" --target .
memory search: fake clock (1 match(es), hub reports 1)
- cards/card-54d4d0fc-b215-4ef1-a1b8-1db01342c148.md [hub] card-54d4d0fc-b215-4ef1-a1b8-1db01342c148
brigadestack memory hub card <card-id> --target . prints the card body, which that checkout never held locally.
Messages, claims and work items
Machines and agents can also pass short messages through the hub. These commands use a message credential, not the admin token:
brigadestack fleet msg count
brigadestack fleet msg identity
brigadestack fleet msg list --unacked --wait 20
count prints the unread total without fetching message bodies. Expired and acknowledged mail is not counted. identity is a read-only check of which principal the credential belongs to. list --wait SECONDS holds the request open for up to 20 seconds until a matching message arrives.
New unread mail also reaches running sessions. Claude Code gets it through its managed UserPromptSubmit and PostToolUse hooks, and Codex through brigadestack work presence-hook --harness codex --stdin --context fleet-inbox. Messages are fenced as untrusted peer content and shown once per session. Delivery never acknowledges a message, and a hub that does not answer within 2 seconds is skipped for the next 60 seconds.
To see everything the hub holds about one work item, run brigadestack fleet work handoff show <work-id> (add --json for machine output). It reads the item, its ownership, checkpoints, reports and recorded run references from one snapshot, and it changes nothing.
A run normally falls back to the local run lock when the hub cannot confirm a repository claim. Add --require-fleet-claim to brigadestack run to refuse the work instead, and to abort if the claim is lost mid-run.