Skip to main content
Glama

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 License

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.

Related MCP server: KittyClaw

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

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:

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
curl -s -H "Authorization: Bearer $(cat token.txt)" http://127.0.0.1:8080/api/v1/projects

Docker

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):

{
  "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

# 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.

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 and the migration guide.

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).

  • 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 · all decisions: 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 and the migration guide.

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. Good first issues are tagged good first issue. Run make test before pushing; CI runs lint + typecheck + tests on Node 22/24.

License

Apache-2.0

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that provides a real-time project management board with cards, sprints, comments, and docs, enabling coding agents to query and edit project state.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Self-hosted kanban board that dispatches AI agent fleets against tickets. The embedded Streamable HTTP /mcp endpoint exposes 7 tools to list projects, read boards and tickets, and create, move and comment tickets from any MCP client.
      30
      AGPL 3.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and humans to collaboratively manage kanban boards and Markdown documentation via MCP tools, with stable item keys, revision-safe editing, and full audit trails.
      AGPL 3.0