The gs:// remote path works — full clone of a 115k-chunk production DB in 5 seconds, incremental syncs in ~4s, ADC auth, zero servers — but nothing in the docs said "point two machines at a bucket and you have a federation", so discovering it meant reading Dolt internals. New page docs/multi-agent/bucket-federation.md walks the whole path: create the bucket path -> bd dolt remote add + bd dolt push to seed -> bd init --remote to birth the second replica -> bd sync on a timer, with the exit-code table a timer branches on and the three rules that set the interval (staleness is the interval; lease TTL and reclaim grace must exceed it; a longer interval means more conflicts, because updated_at is touched by every mutation). Carries the measured cost from a production two-machine deployment (28s cold push, 5s clone, ~4s incremental push, ~1s pull+merge at ~1.3k issues / ~115k chunks) and the failure modes that path actually hits: raw `dolt remote add` leaving the SQL server blind to the remote, a fresh machine with no Dolt commit identity failing even a no-op merge, server-mode credentials being whatever the server inherited at startup (GH#6), remote-name drift between replicas, conflict resolution through the dolt_conflicts tables, and one bucket path per database. Registered in the Mintlify nav and cross-linked from the multi-agent index and from the federation guide, which keeps DoltHub as the zero-config default and points here for the BYO-cloud story.
2.4 KiB
2.4 KiB
| title | description |
|---|---|
| Multi-Agent | Coordinate beads across multiple agents and repositories with routing, cross-repo dependencies, and work handoff |
Beads supports coordination between multiple AI agents and repositories.
Overview
Multi-agent features enable:
- Routing - Automatic issue routing to correct repositories
- Cross-repo dependencies - Dependencies across repository boundaries
- Agent coordination - Work assignment and handoff between agents
Key Concepts
Routing
Routing decides which repository a new bead lands in, based on your role
(contributor vs maintainer) and the routing.* config keys — an explicit
--repo flag always wins. See Multi-Repo Routing
for the decision flow and configuration reference.
Work Assignment
Assign or atomically claim work:
bd assign bd-42 agent-1 # shorthand for bd update bd-42 --assignee agent-1
bd update bd-42 --claim # atomically set assignee + in_progress
bd ready --claim --json # claim the first ready match
Cross-repo Dependencies
Track dependencies across repositories:
bd dep add bd-42 external:other-repo:api-ready
Architecture
┌─────────────────┐
│ Main Repo │
│ (coordinator) │
└────────┬────────┘
│ routes
┌────┴────┐
│ │
┌───▼───┐ ┌───▼───┐
│Frontend│ │Backend│
│ Repo │ │ Repo │
└────────┘ └────────┘
Getting Started
- Single repo: Standard beads workflow
- Multi-repo: Configure routes and cross-repo deps
- Multi-agent: Add work assignment and handoff
Pages in this section
- Routing — automatic issue routing across
repositories and
BEADS_DIRresolution. - Coordination — work assignment and handoff patterns between agents.
- Federation — peer-to-peer sharing of beads across repos and organizations.
- Bucket Federation Quickstart — federate two machines through a GCS or S3 bucket, with no server to run.
- Multi-Repo Migration — moving an existing single-repo setup to multi-repo routing.