# Forking

Copy a sandbox to try something you may want to undo.

`POST /v1/sandboxes/{id}/fork`

```shell
curl -X POST https://agental.io/v1/sandboxes/{id}/fork \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Idempotency-Key: fork-7" \
  -H "Content-Type: application/json" \
  -d '{"name":"fix-login-bug-second-try"}'
```

- The answer is a new running sandbox of the same size, whose disk is a copy of the first.
- It boots fresh, so nothing that was running in the original is started for you.
- The original is left exactly as it was. From then on the two share nothing.
- A fork is a sandbox like any other.
- It answers like a create: `201`, `200` for a replayed key, `202` to wait and resend.
- It is the size of its source, so your plan has to make that size: `402 size_not_on_plan` if it does not.

## From inside the sandbox

An agent in a sandbox can fork the machine it runs on, try one idea in each copy, and keep the one that works. `AGENTAL_SANDBOX_ID` names its sandbox, in its commands and in a shell over SSH alike, and `AGENTAL_API_URL` is where to send the call.

```shell
curl -s -X POST "$AGENTAL_API_URL/v1/sandboxes/$AGENTAL_SANDBOX_ID/fork" \
  -H "Authorization: Bearer $AGENTAL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: try-cache-$AGENTAL_SANDBOX_ID" \
  -d '{"name":"try-cache"}'
```

- Give it a [key](https://agental.io/docs/api-keys) limited to its sandbox, with `sandbox.fork` to fork it, `exec` to run commands in each fork, and `sandbox.delete-own` to delete the forks it made and no other sandbox. A key limited to some sandboxes still reaches the ones it made.
- Each fork is a sandbox of its own, billed as one until it is deleted. Its shells name the fork, not the sandbox it came from.

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)