Skip to main content
POST
Create a sandbox

Authorizations

Authorization
string
header
required

Organization API key (msb_…) - org-scoped programmatic access.

Query Parameters

start
boolean

If true, durably queue the sandbox for immediate orchestrator dispatch.

wait_for
null | enum<string>

Optional lifecycle state to wait for after durable start admission. Lifecycle state an opt-in create request may wait to observe.

Available options:
running
wait_timeout
integer<int64> | null

Server-side wait budget in seconds; valid only with wait_for.

Required range: x >= 0

Body

application/json

What the user sends in POST /v1/sandboxes.

The body is a microsandbox [CloudSandboxSpec] - carried verbatim through the shared [CloudCreateSandboxRequest] envelope (flattened onto the wire) so it can never drift from the cross-repo contract - plus the cloud-only fields that have no place in the shared spec: the globally-unique SSH slug and the registry-credential selection. (Writable-disk size now lives in the spec's resources.disk_size_mib.)

env
object[]

Environment variables visible to commands in the sandbox.

image
object

Root filesystem source. The hosted cloud accepts OCI images only.

init
null | object

Hand off PID 1 to a guest init binary after agentd setup.

labels
object

User-defined labels attached to the sandbox.

lifecycle
object

Sandbox lifecycle policy.

mounts
object[]

Volume mounts.

Cloud volume mount. Internal-tagged mirror of the domain [VolumeMount]; the transient create field is not carried on the wire.

name
string
default:""

Unique sandbox name.

network
object

Network specification.

patches
object[]

Rootfs patches applied before VM start.

Rootfs patch applied before VM start. Twin of [Patch], internally tagged with a snake_case type instead of the domain's external PascalCase tag.

pull_policy
enum<string>
default:if_missing

Pull policy for OCI images.

Available options:
if_missing,
always,
never
resources
object

CPU, memory, and user-facing disk resources.

rlimits
object[]

Sandbox-wide resource limits inherited by guest processes.

runtime
object

Guest runtime options.

security_profile
enum<string>
default:default

In-guest security profile.

Available options:
default,
restricted
registry
object

Registry-credential selection for the image pull. Absent ⇒ Auto (infer the credential from the image's registry host). Credential-only: this never changes where the image is pulled from - the image string controls that - only which stored credential, if any, is presented.

slug
string | null

Optional globally-unique slug - the SSH username token. Lowercase letters, digits, and single hyphens; 3-63 chars. Omitted ⇒ a dictionary slug is generated. Must be globally unique (409 on conflict).

Response

Sandbox created

The API view of a [Sandbox]: an explicit allowlist of user-facing fields. Internal columns (registry selection, sync bookkeeping, resolved refs) never appear; the resolved spec surfaces only as the curated [SandboxSpecResponse].

created_at
string<date-time>
required
ephemeral
boolean
required
id
string<uuid>
required
name
string
required
org_id
string<uuid>
required
slug
string
required
status
enum<string>
required

Sandbox lifecycle status.

Available options:
created,
starting,
running,
stopping,
stopped,
failed
last_failure_message
string | null

Human-readable reason for the last failure.

spec
null | object

Curated projection of the resolved spec; absent until resolved.

started_at
string<date-time> | null

Latest run's start time; null if the sandbox has never run.

status_reason
null | enum<string>

Scheduler condition while status is starting.

Available options:
scheduling,
insufficient_capacity
stopped_at
string<date-time> | null

Latest run's stop time; null while open or never run.