Skip to main content
Glama
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**.

[![CI](https://github.com/poonasor/agent-bureau/actions/workflows/ci.yml/badge.svg)](./.github/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./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)