Skip to main content
POST
Fork sandbox

Authorizations

Authorization
string
header
required

Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.

Headers

Idempotency-Key
string

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.

Maximum string length: 255

Path Parameters

sandboxId
string
required

Public Sandbox id returned by create/list/get sandbox calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Body

application/json
failFast
boolean
default:false

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.

env
object

Replaces the env the fork would otherwise inherit from the source sandbox. Same validation rules as CreateSandboxRequest.env.

environment
string

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.

Examples:

"base"

"customer-demos"

noEnv
boolean

Make the fork no-env (see CreateSandboxRequest.noEnv). A fork of a no-env sandbox is always no-env regardless of this field.

type
enum<string>

Machine size for the fork. Omit to inherit the source sandbox's type. The source sandbox is never modified. Shrinking is rejected with type_too_small when the source's data would not fit the smaller disk.

Available options:
small,
default,
large
ttlSeconds
integer | null
default:3600

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.

Required range: 1 <= x <= 2592000

Response

Fork started. The response id is the new forked sandbox id.

ok
boolean
required
Example:

true

type
string
required

Stable success envelope discriminator added by v1.

Example:

"sandbox.stopping"

id
string
required
status
string
required
Example:

"archiving"

sandbox
object | null
giftLimitNotice
string

Present on resume or fork when a fair-use cap on a gifted account shortened the requested auto-stop time.

conversationId
string

On interrupt, the conversation whose turn was interrupted.