Fork sandbox
Provision a new sandbox from an existing one. Send an Idempotency-Key header to make this call safe to retry after a lost response without creating a second billable fork.
Authorizations
Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.
Headers
Optional exactly-once key for creating a sandbox. Send your own opaque, account-unique value (a UUID) to make POST /sandboxes safe to retry when the response is lost (network timeout, 5xx): the first request creates the sandbox and binds it to the key; every later request with the same account, key, and request body returns that same sandbox instead of creating a second, billable one. Behavior: keys are retained for 24 hours; a concurrent or early retry while the first sandbox is still being minted returns 409 idempotency_in_progress (retry shortly, same key); reusing a key with a different body returns 409 idempotency_key_reused; timeouts and 5xx are safe to retry with the same key; a create that fails before the sandbox exists releases the key within ~2 minutes so a retry can create the sandbox. Omit the header to keep the default (non-idempotent) behavior.
255Path Parameters
Public Sandbox id returned by create/list/get sandbox calls.
^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$Body
Labels of the fork. The fork never takes the source's labels. Same rules as CreateSandboxRequest.labels.
Pass true to fork only if a machine is ready right now. Within about 1.5 s you get the usual 202, or 503 no_ready_machine with no fork created and nothing counted against your start limits.
false creates the fork with monitoring off: Boat keeps no command or process output, process list or CPU/RAM samples for it. Omitted, the fork keeps the source sandbox's setting. true turns it on for the fork, unless the account has monitoring off by default (409 monitoring_off_for_account).
Replaces the env the fork would otherwise inherit from the source sandbox. Same validation rules as CreateSandboxRequest.env.
Optionally pin the fork to a different named sandbox environment. Omit to inherit the source sandbox's environment. Unknown names are rejected with unknown_environment.
"base"
"customer-demos"
Make the fork no-env (see CreateSandboxRequest.noEnv). A fork of a no-env sandbox is always no-env regardless of this field.
Machine size for the fork. Omit to inherit the source sandbox's type. xlarge needs the $100/month plan or higher (403 machine_class_plan_required). The source sandbox is never modified. Shrinking is rejected with type_too_small when the source's data would not fit the smaller disk.
small, default, large, xlarge Auto-stop for the fork, in seconds. Omit for the 1 hour default; the fork does NOT inherit the source sandbox's TTL, so forking a sandbox that has auto-stop disabled still gives you a fork that stops itself. null disables auto-stop, which means nothing will ever stop this sandbox for you.
1 <= x <= 2592000Response
Fork started. The response id is the new forked sandbox id.
true
Stable success envelope discriminator added by v1.
"sandbox.stopping"
"archiving"
Present on resume or fork when a fair-use cap on a gifted account shortened the requested auto-stop time.
On interrupt, the conversation whose turn was interrupted.