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
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. xlarge requires the effective $100 plan or higher and an explicit bare-metal operator allocation.

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