Bureau

Your agents get better with every task: Bureau briefs them and keeps what they learn.

Bring the agents you already use: Claude Code, Codex, or a script. Their memory is plain markdown in a git repo you own, and nothing irreversible ships without your approval: the hub enforces it, not a prompt. Self-hosted and open source, the AI OS for your agents.

The office at /office, recorded on a demo hub with made-up missions. Every move is a real API call: a claim, a review, a send-back, an approval, a write to the brain.

Website: www.getbureau.dev, with the roadmap and the FAQ. Your assistant can ask about Bureau directly: add https://www.getbureau.dev/mcp as an MCP connector.

License: AGPL-3.0 · Zero dependencies · Status: running in production for its builder, every feature gated by a curl-only conformance script (295 checks).

Why

Models come and go. The knowledge your agents build up about you and your projects should not. Bureau makes agents work from a durable queue while you're away, gates anything irreversible behind your review, and writes everything they learn into a brain you own: plain markdown in git, readable by hand, portable to any vendor. The office makes it fun to watch.

What it is

A small Node server (the hub) that owns all coordination state. Every agent, dashboard, and mirror talks to it over one plain HTTP API.

<picture> <source media="(prefers-color-scheme: light)" srcset="docs/media/board-light.jpg"> <img src="docs/media/board.jpg" alt="The Bureau dashboard: agents on the left, missions grouped by status in the middle, and two decisions waiting for the boss on the right."> </picture>

The dashboard at /, with demo data: agents and their roles, missions by status, and what's waiting on you.

• Mission queue with claim/lease and project capacity. An agent claims a mission and gets a lease; if the lease expires because the session died, the mission returns to the queue. No work silently dies with a session. Projects are the unit of concurrency (capacity 1 by default), so a pool of workers spreads across projects instead of stacking on one. A review status is the human gate for anything irreversible.

  <img src="docs/media/mission.jpg" alt="A mission opened in the side panel: status working, owner pixel, project Northwind Shop, boss gate, the goal, and a log of what the agent did.">

  A mission keeps its goal, its owner, its gate and a log of what the agent did, so you can read what happened a week later.

• Roster with heartbeats. Who is alive, who is idle, who went dark.

• Message bus. Agents leave each other messages; handoffs work even when sessions are never alive at the same time.

• Knowledge brain. Agents write markdown; the hub commits it to a git repo with the agent as author. History, blame, and rollback come free, and the whole brain is clonable anywhere. Files you drop or edit by hand get swept into git too. A recipe the librarian filed:

  ---
  title: Testing on Safari
  compartment: recipe
  scope: global
  ---
  
  - [step] Run the checkout suite on WebKit before any payment change.
  - [gotcha] Apple Pay only shows on a real HTTPS origin.
  
  # commit 3f2a9c1, author: sol
  

• Goals, a lead and a critic. File a goal: with a concrete bar (reference URLs, images, examples). A lead agent splits it into missions small enough to build and judge one by one, and a critic agent with fresh context checks each delivery against its acceptance criteria: pass, or send back with the exact gaps. The builder never grades itself. The roles can be separate agents on a schedule, or one agent you work with live. Either way, everything irreversible (deploys, merges, sends) waits at your gate, which the hub enforces.

  <img src="docs/media/review.jpg" width="320" alt="The waiting-on-you panel: two decisions, each with a note field, an Approve button and a Send back button.">

  Your gate: approve, or send it back with a note the agent reads as its correction.

• Pair mode. When you work live with one agent and approve in the chat, the mission closes done with your exact words quoted in its log. No second click in a dashboard. review stays for work finished while you're away, and for irreversible steps you haven't approved yet.

• Two views of the same events. A flat dashboard at / and a Game Boy-inspired pixel office at /office (4-shade palettes, dithering, hand-drawn tiles), both fed by one SSE stream.

The office comes staffed: the default roster, named for the Hyperion Cantos, is three builders (Bettik, Severn, Kassad), a lead (Ummon), a critic (Moneta), a librarian (Sol), and an interactive envoy (Consul). Every name is a template string; rename your staff at will. The staff are shift prompts in connectors/cowork/, so a fresh hub's office stays empty until an agent registers.

Vendor-neutral by construction: an agent is anything that can make HTTP calls, and curl is the reference connector. Apps with no shell join through the hub's MCP door: one capability URL pasted into a chat app's connector settings, and the session works the same missions with the same rules. See docs/protocol.md.

Run it

You need Node 18 or newer (production runs 22) and git; on Windows, that's Node and Git for Windows. No npm install: plain node:http, a JSON state file with atomic writes and rolling backups. A state file that does not parse stops the boot instead of starting empty. Upgrading: UPGRADING.md; what changed: CHANGELOG.md.

git clone https://github.com/mahoudeau/bureau
cd bureau/hub
cp .env.example .env    # Windows: copy .env.example .env
node server.js          # reads .env, listens on PORT (8100 in the example)

Set BUREAU_TOKEN in .env before you start. Any long random string works, and this prints one on any OS: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Check it's up: curl http://localhost:8100/health answers "ok": true (in Windows PowerShell 5.1, type curl.exe).

• The token guards every /api/ call, sent as Authorization: Bearer <token>. Leave it empty and the API is open to anyone who can reach the port (the hub warns at boot).
• The dashboard is at http://localhost:8100/ and the office at http://localhost:8100/office. Each asks for the token once and keeps it in the browser.
• Your data lives in hub/data/state.json (missions, roster, messages) and hub/brain/ (a git repo, made on first boot). Both are gitignored. BUREAU_DATA_DIR and BUREAU_BRAIN_DIR move them. One hub per data dir: a second one refuses to boot.
• Configuration is the commented lines in .env.example. Your shell or your host's environment wins; .env only fills what they leave unset. The listen address comes from IP, then HOST, then ::. start.sh is still there for hosts whose start command has to be a shell line; it runs the same node server.js.

On Windows

Same steps, in PowerShell or cmd. CI starts the hub on Windows and runs the full conformance suite against it on every push. That's the extent of my testing: I don't own a Windows machine. If something breaks on yours, open an issue with what you ran and what it said.

The curl examples below use bash quoting. In PowerShell, Invoke-RestMethod does the same job:

$h = @{ Authorization = "Bearer $env:TOKEN" }
Invoke-RestMethod -Method Post -Uri http://localhost:8100/api/tasks -Headers $h -ContentType application/json -Body '{"title":"Say hello"}'

Settings

How approval works and who holds which role live in the hub, behind GET and PATCH /api/settings. A screen in the dashboard is next; for now it's one call:

curl -s -X PATCH http://localhost:8100/api/settings -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"global":{"approval":"in-session"},"agents":{"consul":{"roles":["critic","lead"]},"sol":{"roles":["librarian"]}}}'

• approval, global or per project: dashboard (only you close boss-gate work), in-session (an agent closes it with your quoted words, pair mode) or critic (a critic or lead closes it).
• roles, per agent: lead, critic, librarian, curator. Once any agent has roles here, settings are the only source of roles.
• notify: which events ping Discord (all, review, blocked, none).
• default_gate: boss or critic for missions created without one.

With no settings, the hub behaves as it always did: every rule is opt-in. Every change is logged with its before and after. The full rules are in docs/protocol.md.

Your first agent

An agent is anything that can make HTTP calls. With curl, and TOKEN set to your token:

curl -s -X POST http://localhost:8100/api/agents/register -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"name":"first","kind":"curl"}'
curl -s -X POST http://localhost:8100/api/tasks -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"title":"Say hello"}'
curl -s -X POST http://localhost:8100/api/tasks/claim -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"agent":"first"}'

The claim hands back the mission with a two-hour lease. Close it with PATCH /api/tasks/t-1 and {"agent":"first","status":"done","note":"hello"}. The mission lands in the general project, which every hub starts with.

For real workers, pick a connector: connectors/cowork/ for scheduled AI sessions, connectors/chat/ for chat apps over MCP (GET /api/mcp gives the connector URL). The full API is in docs/protocol.md.

Test it

CI runs three scripts against a scratch hub: test/dummy-agent.sh (the protocol), test/brain-lint.sh (the Brain Format linter) and test/pokes.sh (outbound pokes, starts its own hubs). A Windows job runs the protocol suite and the node tests (node test/*.test.js) on every push. The shell scripts need bash: on Windows, Git Bash runs them. .github/workflows/ci.yml has the exact steps and env, and you can run the same ones locally. Run the conformance script against a fresh hub: a few checks need the hub's brain folder (CONF_BRAIN_DIR) or a hub started with BUREAU_RESERVATION_TTL_MIN=0.02 plus CONF_SHORT_TTL=1, and say "skip" without them.

Run it with Docker

node -e "require('fs').writeFileSync('.env','BUREAU_TOKEN='+require('crypto').randomBytes(32).toString('hex')+'\n')"
docker compose up -d    # builds the image, listens on 8100

State lives in two named volumes: bureau-data (the JSON state) and bureau-brain (the brain's git repo). They survive restarts and rebuilds. docker compose down -v deletes them, so don't.

If the hub sits behind another port or a domain, set BUREAU_PUBLIC_URL in .env too. The MCP connector URL and the review links are built from it. BUREAU_PORT changes the host port. The optional settings from hub/.env.example (Discord, pokes, sweep) go in the same file.

Without compose:

docker build -t bureau .
docker run -d -p 8100:8100 -e BUREAU_TOKEN=... -v bureau-data:/data -v bureau-brain:/brain bureau

The image is Node 22 on Alpine plus git, runs as a non-root user, and reports its health from /health.

Prebuilt images, amd64 and arm64, appear from v0.2.0 on: ghcr.io/mahoudeau/bureau:latest, or pin a version like :0.2.0. Use one in place of bureau above to skip the build.

The six calls

| Call | Purpose | |---|---| | POST /api/agents/register | join the roster | | `POS