Skip to content
Developer docs
Docs menu

Branches and mounts

Markdown

Copy-on-write workspaces for Agents, FUSE mounts, a sync command, and Git workspaces.

Use a branch

A branch is a copy-on-write layer over a Space's main line, and serves as an Agent's workspace. Content on a branch is not parsed, indexed, or distilled. It goes through normal processing only when merged, so a failed experiment leaves knowledge and memory untouched.

curl
# Open a branch. Keep its id (brn_...).
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "try-new-outline"}'

# Write to it. Main does not change.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/notes/hello.md&branch=$BRANCH_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @hello.md

# See what changed.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/diff" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Merge into main. Idempotency-Key is required here.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/merge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Idempotency-Key: merge-try-new-outline" \
  -H "Content-Type: application/json" \
  -d '{"message": "New outline", "on_conflict": "abort"}'

POST /v2/spaces/{space_id}/branches opens a branch, GET /v2/spaces/{space_id}/branches/{branch_id}/diff shows its path-level changes, POST /v2/spaces/{space_id}/branches/{branch_id}/merge merges it into main, and DELETE /v2/spaces/{space_id}/branches/{branch_id} abandons it.

  • Use the branch id, which starts with brn_, rather than its name in anything that retries: once a branch closes, its name can move to another one.
  • Opening a branch needs only write access to the Space. write_mode is checked at merge, so an Agent in proposal mode can experiment freely.
  • A member with a read_root in the Space cannot use branches. See Permissions.

Read and write on a branch

files, files/batch, tree, tree/operations, uploads, and changes take an optional branch parameter. Without it, they act on main.

  • A branch read checks the overlay, then falls through to the latest on main. A path the branch has not touched shows main as it is now, not as it was when the branch opened.
  • A write to a branch makes no version and counts no writes until a merge. The etag in its response is a content hash and goes back in If-Match.
  • DELETE on a branch hides the file on that branch only, and main is untouched. To undo changes on a branch, roll back to a checkpoint.
  • Symlinks and file modes (symlink, chmod, mode) work on a branch only: main has no symlinks.
  • changes?branch= is the branch's own feed, with cursors from tree?branch= that do not work on main. source: branch events keep only the latest write per path, so treat them as paths to re-read.
  • search and context do not take branch: branch content cannot be found until merged.

Create checkpoints and roll back

A checkpoint records the branch's own changes at one moment. Paths read through to main are not pinned. After a rollback, later checkpoints stay, so a rollback can be undone, and older changes cursors return 410: read tree?branch= again.

curl
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/checkpoints" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "before-refactor"}'

curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/rollback" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"checkpoint_id": "'$CHECKPOINT_ID'"}'

Merge a branch

A merge requires Idempotency-Key. All paths apply or none do, and each becomes a new version on main with message.

  • Each path is compared with the version main had when the branch first touched it; if main changed it since, that is a conflict. By default, the whole merge fails with 409 merge_conflict, and error.conflicts lists each conflict; on_conflict can keep main or overwrite it instead. There is no content merge.
  • With paths only those paths merge, and the branch stays active. Without it the branch ends merged and takes no more writes.
  • An Agent merging a file it does not own needs write_mode: direct. With Prefer: handling=proposal its changes to such files become proposals instead. See Proposals.

Merge as a job

A merge over the synchronous limit runs as a job when it carries Prefer: respond-async, returning 202 with job_id. Follow it with GET /v2/jobs/{job_id}; see Jobs.

curl
# Over 1000 paths: run the merge as a job instead of 409 merge_too_large.
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/branches/$BRANCH_ID/merge" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Idempotency-Key: merge-big-refactor" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d '{"message": "Big refactor", "on_conflict": "abort"}'
  • The job plans every path first: a conflict fails it before anything is written.
  • It then merges in batches and is not atomic. A conflict that appears midway stops it with the merged paths already gone from the branch: merge again for the rest.
  • While the job is queued or running, the branch takes no other merge and no file writes. Renaming, checkpoints, and abandoning still work, and abandoning stops the job.

Expiry and reclaim

Every write moves expires_at out by ttl_days, which you set on creation or with PATCH /v2/spaces/{space_id}/branches/{branch_id}. A branch with no writes expires and becomes abandoned. After a branch is abandoned, expires, or merges, it is kept for branch_reclaim_days days and then reclaimed. Branch storage counts toward storage_bytes. For the defaults, see Rate limits and quotas.

Store branch objects

PUT /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256} stores an opaque object under its hash, to hold Git bundles and overlays. Objects are not paths, do not appear in tree or changes, are not merged, parsed, or indexed, and count toward storage_bytes. On a merged or abandoned branch they stay readable until the branch is reclaimed.

What is in a branch's objects, Git bundles included, cannot be erased until the branch is reclaimed. purge acts on Entries on main only. To get rid of it sooner, abandon the branch and wait branch_reclaim_days days for reclaim.

Coming soon

CLI and mounts

The mirabase CLI is a single binary with no runtime dependencies, which suits sandboxes, and it uses only the public API. It reads MIRABASE_API_KEY (required), MIRABASE_API_URL, and MIRABASE_SPACE. A mount writes to a branch rather than to main, because one editor save produces several writes and renames.

The CLI is not released yet, so you cannot install the commands below today. Branches themselves are live, and you can call every endpoint in the sections above now.
bash
export MIRABASE_API_KEY="mb_live_..."

# Stays in the foreground and prints the branch it opened.
mirabase mount ./workspace --space "$SPACE_ID"

# In another shell:
grep -rn "TODO" ./workspace
sed -i 's/one place/a single place/' ./workspace/notes/hello.md
mirabase drain ./workspace
mirabase branch diff "$BRANCH_ID" --space "$SPACE_ID"
mirabase branch merge "$BRANCH_ID" --message "Wording" --space "$SPACE_ID"
CommandPurpose
mirabase mount <dir> --space s [--branch b] [--read-only]FUSE mount. Opens a branch unless --branch is given
mirabase sync <dir> --space s [--branch b] [--once]For sandboxes without FUSE: pulls, watches local changes, and pushes
mirabase drain [dir] [--timeout 5m] [--ack]Blocks until local writes are uploaded. Exit code 0 means all uploaded, 1 a write was given up or authentication failed, 2 a timeout, 3 another machine overwrote your write
mirabase branch <subcommand>create, list, get, rename, extend, diff, checkpoint, checkpoints, rollback, merge, and abandon
mirabase git save|restore|worktreeGit workspaces, see the next section
  • Consistency is close-to-open: another machine sees new content on its next open. fsync only guarantees a local write, and drain is what makes it visible elsewhere.
  • When two machines write one path, the last write wins.
  • Rename, mkdir, unlink, truncate, the executable bit, and symlinks work. Hard links, device files, and file locks do not.
  • .mirabase/memory/MEMORY.md is read-only in a mount, and writing it returns EROFS.
  • .git/, node_modules/, .venv/, __pycache__/, and .DS_Store are not uploaded by default and stay local. Adjust this with .mirabaseignore, which uses gitignore syntax.
  • On Linux, a mount needs /dev/fuse (and SYS_ADMIN in a container); without them, use mirabase sync. On macOS, install macFUSE or FUSE-T first.

Git workspaces

mirabase git save bundles commits, incrementally after the first save, stores uncommitted and untracked changes as an overlay, and creates a checkpoint whose git field records HEAD, the ref, and the remote URL without credentials. mirabase git restore <checkpoint> <dir> brings it back in a fresh environment and verifies HEAD and the working tree. mirabase git worktree <checkpoint> <dir> --ref r restores it and opens another ref with git worktree.

bash
# In a Git repository: bundle commits, store uncommitted changes, create a checkpoint.
# Without --branch it opens one and remembers it in .git/mirabase-branch.
mirabase git save --space "$SPACE_ID" --name "before-upgrade"

# Somewhere else: restore and verify HEAD and the working tree.
mirabase git restore "$CHECKPOINT_ID" ./repo --space "$SPACE_ID"
  • Bundles and overlays are stored as branch objects and are never sent to a model provider.
  • The staging area is not saved, so restored changes are all unstaged.
  • Files ignored by .gitignore, and .env, are not saved by default. Pass --include-ignored to include them.
  • Saved content cannot be erased until the branch is reclaimed. See Branch objects.

Next steps