# Branches and mounts

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.

```bash
# 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`](https://mirabase.io/developers/api/branches.md#branches-create) opens a branch, [`GET /v2/spaces/{space_id}/branches/{branch_id}/diff`](https://mirabase.io/developers/api/branches.md#branches-diff) shows its path-level changes, [`POST /v2/spaces/{space_id}/branches/{branch_id}/merge`](https://mirabase.io/developers/api/branches.md#branches-merge) merges it into main, and [`DELETE /v2/spaces/{space_id}/branches/{branch_id}`](https://mirabase.io/developers/api/branches.md#branches-abandon) 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](https://mirabase.io/developers/permissions.md#roots).

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

```bash
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](https://mirabase.io/developers/files.md#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}`](https://mirabase.io/developers/api/jobs.md#jobs-read); see [Jobs](https://mirabase.io/developers/conventions.md#jobs).

curl:

```bash
# 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"}'
```

TypeScript:

```ts
const merged = await mirabase.branches.startMerge(branchId, { message: "Big refactor", on_conflict: "abort" });
if ("job_id" in merged) {
  const job = await mirabase.jobs.get(merged.job_id);
  // job.result?.merged counts paths; a failed plan lists job.result?.conflicts.
}
```

Python:

```python
# branch_id is the branch to merge: the id mb.branches.create returned.
merged = mb.branches.start_merge(branch_id, {"message": "Big refactor", "on_conflict": "abort"})
if "job_id" in merged:
    job = mb.jobs.get(merged["job_id"])
    # job["result"]["merged"] counts paths; a failed plan lists job["result"]["conflicts"].
```

- 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}`](https://mirabase.io/developers/api/branches.md#branches-update). 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](https://mirabase.io/developers/conventions.md#rate-limits).

## Store branch objects

[`PUT /v2/spaces/{space_id}/branches/{branch_id}/objects/{sha256}`](https://mirabase.io/developers/api/branches.md#branches-putobject) 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.

> **Warning:** 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 (Coming soon)

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.

> **Note:** 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"
```

| 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. `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 (Coming soon)

`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](https://mirabase.io/developers/branches.md#objects).

## Next steps

- [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#snapshots): use a snapshot when all you need is a fixed point to read from.
- [Permissions](https://mirabase.io/developers/permissions.md): who may merge, and when an Agent's change becomes a proposal.
- [API conventions](https://mirabase.io/developers/conventions.md#idempotency): a merge requires an idempotency key.
