bureau
by poonasor
README.md
# Agent Bureau
**Self-hosted tasks + docs for agent fleets.** One app, one database, one MCP endpoint.
Agent Bureau merges what Vikunja (kanban/tasks) and Outline (knowledge base) each do half of
into a single lightweight service designed for teams where **most of the writers are agents**.
[](./.github/workflows/ci.yml)
[](./LICENSE)
```mermaid
flowchart LR
H["Humans<br/>browser / CLI"] --> API
A["Agents<br/>MCP clients"] --> MCP["/mcp"]
S["Other services"] --> API["REST /api/v1"]
MCP --> APP
API --> APP["Agent Bureau<br/>one process"]
APP --> DB[("SQLite<br/>WAL")]
APP -->|signed webhooks<br/>retries + replay| W["Your automations,<br/>relays and bots"]
```
## Why another tool?
Because we ran Vikunja + Outline with a fleet of coding agents, and three things kept breaking:
1. **Webhook delivery was fire-and-forget.** Vikunja retries for a few seconds in memory, then drops.
A bot mid-restart means a lost card wake, silently. Agent Bureau writes an event to a transactional
outbox **in the same commit as the change**, then delivers with retries over hours, a full delivery
log, and byte-stable replay.
2. **Events didn't say who did it.** A bot reacting to its own write is the classic agent echo loop.
Every Agent Bureau write carries `actor: {id, type: human | bot | system}` — and webhook subscriptions
can exclude actors entirely.
3. **Tasks and docs lived in different apps**, with two auth paths, two MCP servers, and no link
between a card and the spec it implements. In Agent Bureau a card↔doc link is a foreign key, and one
MCP endpoint serves both.
Everything is append-only auditable: every field change lands in a status history with actor, transport (`via: rest | mcp | ui | cli | rule`) and rule id.
## What works today (v0.2)
- **Tasks**: projects, board views with buckets (WIP limits, default/done buckets), labels,
assignees, comments, priorities, due dates, `percent_done`. Moving a card into the *done* column
marks it done — and syncs every other board view of the project. Safe partial updates
(`PATCH`) that never wipe fields you omit.
- **Docs**: collections, nested markdown documents, revisions on every save with optimistic
concurrency (409 on stale revision), slug stability with 301 redirects for renamed docs.
- **Search**: SQLite FTS5 (BM25) across tasks and documents with snippets.
- **Card↔doc links**: both directions, with `link.created` / `link.deleted` events.
- **Agent surfaces**: one MCP endpoint (`/mcp`, Streamable HTTP, 18 tools) and a clean REST API
with `bureau_`-prefixed tokens (`read`/`write` scopes). Bots are first-class users with owners.
- **Webhooks**: native signed envelopes (`X-Bureau-Signature`), event/project/actor filtering,
retry schedule (8 attempts ≈ 5h42m), auto-disable, delivery log, replay.
- **Vikunja compat shim**: existing bots keep their Vikunja v1 API calls and
`X-Vikunja-Signature` webhooks — only the base URL and token change. Upstream quirks
(full-object-POST field wipes, `task.comment.edited` naming, numeric error codes) are
reproduced and contract-tested.
- **Outline compat shim**: `documents.*` / `collections.*` RPC methods with Outline envelopes,
`lastRevision` 409s, `editMode` patching, and markdown export.
- **Importers**: `bureau import vikunja|outline` reads the source systems' APIs, preserves ids
(tasks keep numeric ids; docs keep uuid+urlId so every old URL resolves), records an `id_map`,
and verifies counts against the source.
- **Automation rules**: "when a card enters bucket X, assign user Y / add label Z" — server-side,
cascade-free, attributed to `system` with the rule id.
- **Deploy**: one Docker image, one SQLite file. Backups are `cp` (plus WAL checkpoint).
## Quickstart
```bash
git clone https://github.com/poonasor/agent-bureau && cd bureau
npm install
npm run dev # http://127.0.0.1:8080
```
Create an admin and a token:
```bash
npx tsx src/main.ts users create --username alice --password "long-passphrase"
npx tsx src/main.ts users set-admin --username alice
npx tsx src/main.ts tokens create --user alice --title first --stdout > token.txt && chmod 600 token.txt
```
```bash
curl -s -H "Authorization: Bearer $(cat token.txt)" http://127.0.0.1:8080/api/v1/projects
```
### Docker
```bash
export BUREAU_SECRET_KEY=$(openssl rand -base64 32)
docker compose up -d --build
curl -s http://127.0.0.1:8080/health
```
Then exec into the container to bootstrap (`docker compose exec bureau node dist/main.js …`).
### Point an agent at it
Any MCP client (Claude Desktop, ZCode, your own agent):
```jsonc
{
"mcpServers": {
"bureau": {
"url": "http://your-host:8080/mcp",
"headers": { "Authorization": "Bearer bureau_…" }
}
}
}
```
One endpoint, both domains: `create_task`, `move_task`, `search`, `create_document`, `link_doc`, …
## The API in one minute
```bash
# projects come with a board, default buckets and a done column
curl -X POST …/api/v1/projects -d '{"title":"Launch"}'
# agents write with PATCH semantics — omitted fields are never wiped
curl -X PATCH …/api/v1/tasks/42 -d '{"percent_done":0.5}'
# moves apply done-bucket rules and fire task.moved webhooks
curl -X POST …/api/v1/tasks/42/move -d '{"view_id":1,"bucket_id":3}'
```
Full reference: [docs/api.md](./docs/api.md).
## Coming from Vikunja + Outline?
Your bots don't have to be rewritten. Point them at the compatibility shims —
`/compat/vikunja/api/v1` and `/compat/outline/api` — and import your data with
`bureau import vikunja|outline --verify`. Tasks keep their ids, document URLs keep resolving,
and Vikunja-signed webhooks keep their HMAC scheme. Details:
[docs/compatibility.md](./docs/compatibility.md) and the
[migration guide](./docs/migration-from-vikunja-outline.md).
## Design in 60 seconds
- **One process + SQLite (WAL, `synchronous=FULL`)**. The outbox is a table; the delivery worker
is a loop in the same process. No Redis, no queue. Postgres remains available as a future
storage backend if you outgrow a single file (see [ADR-0002](./docs/adr/ADR-0002-sqlite-first.md)).
- **Transactional outbox.** Change + event commit together or not at all; fan-out and delivery
happen after commit. Deliveries store their exact signed bytes, so retries and replays are
byte-identical.
- **Actor tagging everywhere.** `human` / `bot` / `system` on every event, history row and webhook.
- **Clean-room.** No code was copied from Vikunja (AGPL) or Outline (BSL). Agent Bureau is Apache-2.0.
More: [docs/architecture.md](./docs/architecture.md) · all decisions: [docs/adr/](./docs/adr/)
## Migrating from Vikunja / Outline
Import tooling and an API compatibility layer (existing bots keep working with a token swap) are
the next milestones — see [docs/roadmap.md](./docs/roadmap.md) and the
[migration guide](./docs/migration-from-vikunja-outline.md).
## Status
v0.1 — core platform, stable API surface forming. **Expect breaking changes until 1.0**, tracked
in the roadmap. The UI is intentionally minimal right now (read-only doc view; full board/editor
ships in M3) — the API and MCP are the product today.
## Contributing
PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Good first issues are tagged
[`good first issue`](https://github.com/poonasor/agent-bureau/issues?q=is%3Aissue+label%3A%22good+first+issue%22).
Run `make test` before pushing; CI runs lint + typecheck + tests on Node 22/24.
## License
[Apache-2.0](./LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data