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
labels
object

Labels of the fork. The fork never takes the source's labels. Same rules as CreateSandboxRequest.labels.

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.

monitoring
boolean

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

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

Available options:
small,
default,
large,
xlarge
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.