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

```sh
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.

```ts tab=TypeScript
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 }
```

```python tab=Python
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`.