Skip to main content
POST
Create a sandbox

Authorizations

Authorization
string
header
required

Personal byk_ API key; user-principal, resolved to a tenant by org context.

Headers

X-Bonya-Organization-ID
string

Org context. Omitted means the caller's personal organization. A well-formed non-member org is 404; malformed is 400.

Idempotency-Key
string

Absent means server-generated, which provides no deduplication; only client-supplied keys dedupe.

Maximum string length: 255

Query Parameters

wait
enum<string>
Available options:
ready

Body

application/json
template_id
string

Omit to use the deployment's configured default template.

template_revision
integer
template_version
string
snapshot
string

Snapshot id to start from.

image
string

OCI image reference.

gpu
object

Requests a GPU sandbox. Requires image (or an image template); cannot be combined with snapshot or template_version. Valid type/count pairs come from GET /v1/sandbox/gpu-options, which is empty when no GPU capacity is configured. Subject to the organization's concurrent-GPU limit.

network
object
env
object
secret_sets
string[]

Secret set names (see /v1/secret-sets).

name
string
Maximum string length: 80

Response

Created and ready (wait=ready)

id
string
required

Sandbox id, for example sb-bpyk22c3ei3hfx.

name
string
required
organization_id
string
required
template_version
string
required
state
enum<string>
required
Available options:
creating,
running,
warm,
cooling,
cold,
waking,
deleting,
deleted,
failed,
lost
generation
integer
required
vcpus
integer
required
memory_mib
integer
required
user_layer_bytes
integer
required
created_at
string<date-time>
required
network
object
required
network_revision
integer
required
network_applied_revision
integer
required

Revision the node is known to enforce; below network_revision until a change is applied.

failure_reason
string
started_at
string<date-time>
deleted_at
string<date-time>
parent_snapshot_id
string

The named snapshot it was created from.

forked_from_sandbox_id
string
pause_source
string

Who paused it: idle, requested, memory_pressure.

image
object
gpu
object
exec_capability_jws
string

Exec capability token, present on responses that carry one.