# Forks

> Branch a running or stopped sandbox into a new, independent copy. Perfect for exploring multiple agent paths or eval branches from one base state.

A **fork** creates a new, independent sandbox from an existing sandbox's `/workspace` and
configuration. Use it to branch an agent run, compare multiple eval paths in parallel, or keep a
base sandbox intact while you experiment in a copy. The fork and its source are fully independent
afterward: changes in one never affect the other.

## Fork vs. snapshot

- A **fork** is an immediate, one-shot copy from one sandbox into one new sandbox. Reach for it when
  you already have a sandbox in the exact state you want to branch *right now*.
- A **[snapshot](./snapshots.md)** is a named, reusable artifact that can create many sandboxes
  later. Reach for it when you want a golden base you launch repeatedly.

Both copy `/workspace` plus configuration. Neither copies running processes, RAM, terminal
sessions, preview links, or command history.

## Fork a sandbox

```python
from flaxcloud import FlaxClient

flax = FlaxClient()

sb = flax.create_sandbox(template="python", env={"CASE": "base"})
sb.upload("/workspace/input.txt", "baseline")

fork = sb.fork(metadata={"branch": "eval-a"})
fork.upload("/workspace/input.txt", "changed in fork")

print(sb.read_text("/workspace/input.txt"))    # baseline
print(fork.read_text("/workspace/input.txt"))  # changed in fork
```

```ts
const sb = await flax.createSandbox({ template: "python", env: { CASE: "base" } });
await sb.upload("/workspace/input.txt", "baseline");

const fork = await sb.fork({ metadata: { branch: "eval-a" } });
await fork.upload("/workspace/input.txt", "changed in fork");

console.log(await sb.readText("/workspace/input.txt"));   // baseline
console.log(await fork.readText("/workspace/input.txt")); // changed in fork

// Or fork by id:
const fork2 = await flax.forkSandbox(sb.id);
```

You can fork a **live or stopped** source sandbox. The `metadata` map is an optional set of labels
you can attach to identify the branch later.

## Fan out multiple branches

A common agent pattern is to prepare a base sandbox, then fork it several times to explore
different strategies concurrently:

```python
base = flax.create_sandbox(template="python")
base.upload("/workspace/task.json", task_json)

branches = [base.fork(metadata={"branch": name}) for name in ("a", "b", "c")]
for b in branches:
    b.run("python3 solve.py", background=True)  # each explores independently
```

## HTTP API

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/v1/sandboxes/{id}/fork` | Create an independent copy of a sandbox. |

The optional body is `{"metadata": { ... }}`. See the [API reference](./api.md).

## Notes

- Each fork is a full sandbox and counts against your concurrent-sandbox and storage
  [limits](./plans-and-limits.md). Destroy branches you're done with.
- The async clients mirror the same surface (`await sb.fork()`, `await flax.fork_sandbox(id)`).