Skip to main content
POST
Create a sandbox

Authorizations

Authorization
string
header
required

Personal access token (msb_pat_…) or session JWT - the credential an agent acts with on a user's behalf.

Path Parameters

slug
string
required

Organization slug

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 carries the shared microsandbox [CloudCreateSandboxRequest] union. Its source-specific and common [CloudSandboxSpec] fields stay flat on the wire beside the cloud-only SSH slug and registry-credential selection.

name
string
default:""
required

Unique sandbox name.

reference
string
required

OCI image reference.

source
enum<string>
required
Available options:
oci
env
object[]

Environment variables visible to commands in the sandbox.

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.

Persistent volume mounted at a path inside the sandbox.

network
object

Network specification.

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
patches
object[]

Rootfs patches applied before VM start.

Filesystem change applied before the sandbox starts. The type field selects the operation.

pull_policy
enum<string>

OCI image pull policy.

Available options:
if_missing,
always,
never
resources
object

CPU, memory, and writable-disk resources.

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

Sandbox details and resolved configuration.

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,
temporarily_unavailable,
recovery_decision_required,
stopping,
stopped,
failed
automatic_recovery_ends_at
string<date-time> | null

When an explicit recovery choice becomes necessary.

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.

temporarily_unavailable_since
string<date-time> | null

When the current worker outage became user-visible.