Forking

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

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.

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

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]