Beads Backend

Dotbrain keeps each project's plans and tasks in Beads (bd), a dependency-aware issue tracker built on Dolt. This page covers the backend modes, how to choose one, and the commands that manage them.

Modes

	embedded (default)	server	none
Where state lives	A local Dolt store in the Brainspace	A shared Dolt sql-server	Nowhere
Sync across machines	Optional, through a Dolt remote	Live	n/a
Setup	None	beads.server in config.yaml	None
Good for	Most projects	Several machines working at once	Projects tracked elsewhere, such as GitHub Issues

If you are unsure, start embedded. Moving to server later keeps history.

How Dotbrain Decides

Two files are involved:

• ~/dotbrain/config.yaml holds machine-wide server defaults under beads.server.
• .brain/project.yaml picks the mode per project with beads.mode. Leaving it out uses server when a shared server host is configured, otherwise embedded.

# .brain/project.yaml
beads:
  mode: server
  database: my_app_beads   # optional; defaults to the project name

See Configuration for the full shape.

Server Mode

Point config.yaml at your sql-server once per machine:

# ~/dotbrain/config.yaml
beads:
  server:
    host: db.example.internal
    port: 3307
    user: beads
    ssh_host: bastion.example.internal   # optional SSH hop, used by drop-db

WARNING

Never put passwords or tokens in config.yaml. Keep credentials in your secrets store.

Then set beads.mode: server in the project and run dotbrain wire or dotbrain beads sync.

Commands

beads sync

Syncs local tracker state from declarations: attaches server trackers, initializes embedded ones, and pulls only when an embedded remote is declared. Disabled Beads is a no-op; a local embedded tracker without a remote is prepared without a pull. Sync never pushes or changes wiring.

dotbrain beads sync --dry-run    # preview
dotbrain beads sync              # the current repo's project
dotbrain beads sync --all        # every Brainspace that uses beads

Run it on a fresh machine after cloning your dotbrain home.

Selection uses the wired Brainspace identity, including a worktree or nested directory. From elsewhere, use --project <name>; --home <path> overrides the data root. Custom databases and remote URLs come from declarations. A declared URL must match a named tracker remote; otherwise sync reports an actionable error rather than pulling another remote. Configure a missing binding with bd dolt remote add <name> <declared-url>, then repeat sync.

--json returns one result with per-project outcomes; independent targets continue after failures. Tracker subprocess waits are bounded. Sync, missing-tool, or pull failures exit unsuccessfully.

beads migrate

Moves an embedded tracker onto the sql-server with its history.

dotbrain beads migrate --dry-run   # print the planned bd sequence
dotbrain beads migrate             # the current repo's project
dotbrain beads migrate --all       # every embedded Brainspace

Migration keeps the full Dolt history, embedded data, and a backup for rollback. It verifies issue counts before reporting a verified migration and preserves unrelated project configuration. Target connection overrides use --server-host, --server-port, and --server-user; --database is a single-project override. Named selection respects the declared custom database when no override is supplied.

Cleaning Up

dotbrain beads list-db lists the databases on the server. dotbrain beads drop-db removes one.

dotbrain beads list-db --server-host db.example.internal --json
dotbrain beads drop-db orphaned_tracker --server-host db.example.internal --dry-run
dotbrain beads drop-db orphaned_tracker --server-host db.example.internal --yes

Database arguments are identifiers, not project selectors; orphaned databases remain manageable. Dropping requires --yes or a preview and rejects unsafe or protected names. The same connection options apply to administration; --ssh-host adds an optional SSH hop.

DANGER

drop-db deletes the remote database and every issue in it. It is separate from dotbrain unwire on purpose: unwire disconnects a repo, drop-db destroys tracker data.

Working With the Tracker

Agents drive Beads through the manage-work-graph skill, but you can use bd directly in any wired repo:

bd ready              # issues with no open blockers
bd show <id>          # one issue with its dependencies
bd list --status open

Only an item's assignee can close it, release it, or reassign it. To close an item someone else holds, close it under their actor and name yourself in the reason:

bd close <id> --actor <assignee> --reason "<reason> (closed by <you>)"

Avoid bd close --force, which also skips gates and open children.

Upgrading bd

dotbrain is qualified on bd 1.3.1; dotbrain doctor warns when an older release is on PATH. Before upgrading from 1.2.x, export each tracker with the version you have:

bd export --all -o <backup>.jsonl

An embedded tracker migrates its schema on first use. A shared server does not: upgrade bd on every machine that uses the server first, then run bd migrate schema once per database. Until then the server refuses bd dolt pull and bd dolt push.