> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fork a Sandbox

> Branch a running sandbox — or a saved snapshot — into N independent copies

`POST /v1/agents/runtime/{runtime_id}/fork` · `POST /v1/agents/snapshots/{snapshot}/fork`

Fork captures the parent's state **once**, then starts every child from that capture. The parent keeps running with its own ID. Each child is an ordinary sandbox — its own ID, timeout, and filesystem.

Results are **per-child**: one failure never fails the request. Inspect every entry in `children`.

```python Python theme={"dark"}
from gravixlayer import GravixLayer, ForkError

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"
sandbox.file.write("/workspace/data.txt", "shared\n")

# Fork a running sandbox into 4 children
result = client.runtime.fork(sandbox.runtime_id, count=4)

for child in result.runtimes:
    print(child.runtime_id, child.file.read("/workspace/data.txt").content)
    child.kill()
for err in result.errors:
    print("child failed:", err.code, err.error)

# Fork a saved snapshot instead — no capture, parent need not be alive
result = client.snapshots.fork("my-snapshot", count=3)
```

```typescript TypeScript theme={"dark"}
import { GravixLayer, forkRuntimes, forkErrors } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"
await sandbox.file.write("/workspace/data.txt", "shared\n");

// Fork a running sandbox into 4 children
const result = await sandbox.fork({ count: 4 });

for (const child of forkRuntimes(result)) {
  console.log(child.runtimeId);
}
for (const err of forkErrors(result)) {
  console.log("child failed:", err.code, err.error);
}

// Fork a saved snapshot instead — no capture, parent need not be alive
const fromSnap = await client.snapshots.fork('my-snapshot', { count: 3 });
```

```bash CLI theme={"dark"}
# Requires: GRAVIXLAYER_API_KEY, jq

# Fork a running sandbox into 4 children
gravixlayer runtime fork "$RT" --count 4

# Keep the capture as a named snapshot (requires --persist-snapshot)
gravixlayer runtime fork "$RT" --count 2 --persist-snapshot --name shared-base

# Per-child overrides
gravixlayer runtime fork "$RT" --count 3 --timeout 600 \
  -e WORKER=1 --metadata '{"batch":"a"}'

# Fork a saved snapshot instead (name or id) — no capture, parent need not be alive
gravixlayer snapshot fork my-snapshot --count 3
```

```bash cURL theme={"dark"}
# Requires: GRAVIXLAYER_API_KEY, jq
API="https://api.gravixlayer.ai/v1"
AUTH=(-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json")

# Fork a running sandbox into 4 children
curl -sS -X POST "$API/agents/runtime/$RT/fork" "${AUTH[@]}" \
  -d '{"count": 4}' | jq '.children[] | .runtime.runtime_id // .error'

# Fork a saved snapshot instead (name or id)
curl -sS -X POST "$API/agents/snapshots/my-snapshot/fork" "${AUTH[@]}" \
  -d '{"count": 3}' | jq '.children[] | .runtime.runtime_id // .error'
```

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `count` | integer | No | Children to start, 1–100 (default 1) |
| `timeout_seconds` | integer | No | Timeout applied to each child. The parent's timeout is unaffected |
| `persist_snapshot` | boolean | No | Live-fork only. Keep the capture as a named snapshot (default `false` — cleaned up once children start) |
| `name` | string | No | Live-fork only. Name for the persisted snapshot. Requires `persist_snapshot: true` |
| `env_vars` | object | No | Extra environment variables on every child, merged over the parent's |
| `metadata` | object | No | Extra metadata merged over the parent's on each child |

## Response

| Field | Type | Description |
| - | - | - |
| `children` | array | Per-child results in request order — each entry is a `runtime` object (same fields as a created sandbox, e.g. `runtime_id`, `status`) on success, or `{code, error}` on failure |
| `snapshot_id` | string | Snapshot the children were created from |
| `snapshot_persisted` | boolean | `true` only when `persist_snapshot: true` was passed (live fork); always `true` on a snapshot fork |
| `parent_runtime_id` | string | Parent runtime on a live fork; absent on a snapshot fork |

## Notes

* The parent must be **running**. A paused parent returns `409 runtime must be running to fork` — resume and retry.
* Children inherit the parent's environment variables; per-session credentials are regenerated on each child.
* A child that shows `status: "running"` may take a moment before commands and file operations respond — retry briefly on a fresh child.
* A forked child is fully independent: writes on one child never appear on the parent or siblings.
* With `persist_snapshot: false` (default) the capture is removed once every child has started; it does not appear in your snapshot list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.