Branches and mounts
MarkdownCopy-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.
# 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_modeis checked at merge, so an Agent inproposalmode can experiment freely. - A member with a
read_rootin 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
writesuntil a merge. Theetagin its response is a content hash and goes back inIf-Match. DELETEon 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 fromtree?branch=that do not work on main.source: branchevents keep only the latest write per path, so treat them as paths to re-read.searchandcontextdo not takebranch: 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 -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, anderror.conflictslists each conflict;on_conflictcan keep main or overwrite it instead. There is no content merge. - With
pathsonly those paths merge, and the branch staysactive. Without it the branch endsmergedand takes no more writes. - An Agent merging a file it does not own needs
write_mode: direct. WithPrefer: handling=proposalits 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.
# 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.
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.
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"| Command | Purpose |
|---|---|
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|worktree | Git workspaces, see the next section |
- Consistency is close-to-open: another machine sees new content on its next open.
fsynconly guarantees a local write, anddrainis 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.mdis read-only in a mount, and writing it returnsEROFS..git/,node_modules/,.venv/,__pycache__/, and.DS_Storeare not uploaded by default and stay local. Adjust this with.mirabaseignore, which uses gitignore syntax.- On Linux, a mount needs
/dev/fuse(andSYS_ADMINin a container); without them, usemirabase 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.
# 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-ignoredto include them. - Saved content cannot be erased until the branch is reclaimed. See Branch objects.
Next steps
- Sync, snapshots, and export: use a snapshot when all you need is a fixed point to read from.
- Permissions: who may merge, and when an Agent's change becomes a proposal.
- API conventions: a merge requires an idempotency key.
