Build

Forks

Copy a space, or one folder of it, into a sandbox in an instant, work there, see what changed, and apply what you keep.

A fork is a new space made from another one (or from one folder of it) without copying any bytes. It shares the original's files, data key and bucket, so forking terabytes takes a moment. Work in it like any space, through Finder, the CLI, the API or MCP, then list what changed and bring back the parts you want.

Typical uses: give an AI agent a sandbox to reorganize or retag; cut an alternative version of an episode; try a color pass without touching the delivered files.

Shell

sidespace fork create "Film A" "Film A – color test" --path /Ep01
# …change files, tags, move and delete things in the fork…
sidespace fork changes "Film A – color test"
sidespace fork apply "Film A – color test" --dry-run
sidespace fork apply "Film A – color test" /Ep01/color      # only this folder
sidespace fork apply "Film A – color test" --force          # overwrite conflicts too

API

To	Call
Fork (any member; you manage the fork)	`POST /v1/spaces/{sid}/forks` with `name` and optional `path`
A space's forks you're in	`GET /v1/spaces/{sid}/forks`
What changed in a fork	`GET /v1/spaces/{fork}/fork/changes`
Apply changes to the original	`POST /v1/spaces/{fork}/fork/apply` with optional `paths`, `force`, `dry_run`

Changes and conflicts

Each change is one of added, modified, metadata (same bytes, different sidecars), moved (including renames) and deleted.

A file that also changed in the original after the fork is a conflict, and apply skips it unless you pass force. With force, the fork's version wins and the people whose saves it replaces are notified as usual. Nothing is lost: their versions stay in history.

Applying needs editor rights in the original, and it writes as you, so the journal, webhooks, notifications, sidecar validation and namespace ownership all apply as if you made the changes there.

Forks for agents

A token limited to some spaces may fork them, and the forks it makes are added to its spaces automatically. An agent can open its own sandbox and work there without ever reaching other spaces.

const sandbox = await side.fork("Film A", "Film A – agent", { path: "/Ep01" });
await side.upload(sandbox, "/notes.md", "# ideas\n");
console.log(await side.forkChanges(sandbox));     // [{ kind: "added", path: "/notes.md", … }]
await side.applyFork(sandbox, { dryRun: true });
await side.applyFork(sandbox);                     // conflicts skipped unless { force: true }

sandbox = side.fork("Film A", "Film A – agent", path="/Ep01")
side.upload(sandbox, "/notes.md", "# ideas\n")
print(side.fork_changes(sandbox))
side.apply_fork(sandbox, dry_run=True)
side.apply_fork(sandbox)

The MCP tools are fork_space, fork_changes and apply_fork.