# Run the backend

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.

> Prompt for your coding agent:
>
> Help me run the BrigadeStack backend so my machines share claims, runs and memory.
>
> Read https://brigadestack.com/docs/guides/fleet-hub and ask me which setup fits: a Proxmox LXC or a Docker or Podman container. Then follow that guide one step at a time.
>
> Tell me what each step changes and on which machine. Keep the backend on a private network such as Tailscale. Never publish it to the internet or behind a public tunnel.
>
> Create tokens on the hub host and store them in files only the service user can read. Never ask me to paste a token into this chat, and never put one in a command line or source file.
>
> When the backend is up, run the health and status checks from the guide, then enroll this machine as a node and confirm it shows up.

## 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](/docs/guides/fleet-hub-proxmox) | Recorded runbook, runs under systemd | You have a Proxmox VE 9.x host and want a small dedicated container |
| [Docker or Podman](/docs/guides/fleet-hub-containers) | 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_id` from 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:

```bash
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](/docs/guides/fleet-hub-proxmox#7-enroll-and-configure-each-client) 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 roughly 4,000 to 10,000 heartbeat writes per second in our benchmarks, where the Python hub handled 200 to 460. That is about 8 to 47 times faster. The multiplier depends heavily on disk speed: the slower the disk, the bigger Rust's lead looks, so read the absolute numbers first.

| Setup | Rust, OK writes/s | Python, OK writes/s | Ratio |
|---|---|---|---|
| 16 clients, database on the real disk | 3,900 to 4,522 | 458 to 459 | 8.5x to 9.8x |
| 32 clients on 1 vCPU and 512 MiB, real disk | 5,143 to 5,352 | 441 to 450 | 11.4x to 12.1x |
| 16 clients, database in a slow temp location | 2,562 to 2,936 | 189 to 194 | 13.6x to 15.1x |
| 32 clients on 1 vCPU and 512 MiB, slow temp location | 3,486 to 4,433 | 195 to 200 | 17.9x to 22.1x |
| 64 clients, slow temp location | 8,845 to 10,224 | 225 to 229 | 39x to 45x |
| 64 clients mixed with other work, slow temp location | 8,815 to 9,131 | 187 to 205 | 45x to 47x |
| 256 clients, slow temp location | 6,709 to 6,931 | 229 | 29x to 30x |

Each row is 30-second runs with FULL durability on both engines, on an Intel Core Ultra 9 285, on 2026-11-17. The slow temp location was an ext4 image on a loop device. Moving only the database to the real disk roughly doubled Python's throughput and raised Rust's by about half. At 256 clients Rust refused no connections. An earlier run on 2026-11-05 measured 31 times at the 32-client, 1 vCPU setting ([`engines/hub/bench/S6.md`](https://github.com/escoffier-labs/brigade/blob/main/engines/hub/bench/S6.md)). 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:

```bash
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:

```bash
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:

```bash
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:

```toml
[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:

```bash
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](#enroll-a-machine)), add a `[hub]` table to the repo's `.brigade/memory-care.toml`:

```toml
[hub]
mode = "sync"
scope = "repo:me/my-app"
read_scopes = ["repo:me/my-app"]
```

Then check that the backend answers:

```bash
brigadestack memory hub status --target .
```

```text
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:

```bash
brigadestack memory hub push --target . --yes
```

```text
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:

```toml
[hub]
mode = "read"
read_scopes = ["repo:me/my-app"]
```

```bash
brigadestack memory search "fake clock" --target .
```

```text
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:

```bash
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.