Create a new sandbox

Sandbox created successfully

POST /api/v1/sandbox/create

cURL

curl --request POST \
  --url 'https://api.sandbox.stateset.app/api/v1/sandbox/create' \
  --header "Authorization: Bearer $STATESET_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cpus": "string",
  "memory": "string",
  "isolation": "container",
  "timeout_seconds": 250,
  "env": {},
  "gpu": {
    "count": 2,
    "type": "standard",
    "memory_gb": 1
  },
  "image": "https://cdn.example.com/products/tent-2p.jpg",
  "desktop_os": "linux"
}'

201

{
  "sandbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "creating",
  "pod_ip": "string",
  "sandbox_epoch": 1,
  "allocated_vcpu": 1.5,
  "allocated_memory_gib": 1.5,
  "created_at": "2026-08-31T14:22:05Z",
  "expires_at": "2026-08-31T14:22:05Z",
  "max_expires_at": "2026-08-31T14:22:05Z",
  "max_lifetime_seconds": 250,
  "remaining_extend_seconds": 250,
  "lifetime_used_seconds": 250,
  "lifetime_used_percent": 7.5,
  "startup_metrics": {
    "total_ms": 250,
    "pod_creation_ms": 250,
    "pod_ready_ms": 250,
    "phases": [
      {
        "name": null,
        "durationMs": null
      }
    ]
  }
}

Request body

CreateSandboxRequest

session_id · string (uuid)

cpus · string

memory · string

isolation · string

timeout_seconds · integer

env · object

gpu · object

image · string

desktop_os · string · required

Response

SandboxResponse

sandbox_id · string (uuid) · required

Unique sandbox identifier

org_id · string · required

Organization that owns this sandbox

session_id · string · required

Session identifier

status · string · required

Current sandbox status

pod_ip · string

Internal pod IP address

sandbox_epoch · integer · required

Sandbox recycle epoch counter

allocated_vcpu · number

Allocated vCPU cores

allocated_memory_gib · number

Allocated memory in GiB

created_at · string (date-time) · required

ISO 8601 creation timestamp

expires_at · string (date-time) · required

ISO 8601 expiration timestamp

max_expires_at · string (date-time) · required

Maximum possible expiration

max_lifetime_seconds · integer · required

Maximum sandbox lifetime in seconds

remaining_extend_seconds · integer · required

Seconds available for extension

lifetime_used_seconds · integer · required

Seconds of lifetime consumed

lifetime_used_percent · number · required

Percentage of lifetime consumed

startup_metrics · object

Startup timing breakdown

Show startup_metrics

total_ms · number · required

Total startup time in milliseconds

pod_creation_ms · number · required

Pod creation time

pod_ready_ms · number · required

Time until pod ready

phases · object[] · required

Show phases

name · string · required

durationMs · number · required

Status codes

Code	Meaning
201	Sandbox created successfully
202	Request queued due to concurrency limits
400	Invalid request
401	Authentication required
429	Concurrent limit exceeded

cURL

curl --request POST \
  --url 'https://api.sandbox.stateset.app/api/v1/sandbox/create' \
  --header "Authorization: Bearer $STATESET_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cpus": "string",
  "memory": "string",
  "isolation": "container",
  "timeout_seconds": 250,
  "env": {},
  "gpu": {
    "count": 2,
    "type": "standard",
    "memory_gb": 1
  },
  "image": "https://cdn.example.com/products/tent-2p.jpg",
  "desktop_os": "linux"
}'

201

{
  "sandbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "creating",
  "pod_ip": "string",
  "sandbox_epoch": 1,
  "allocated_vcpu": 1.5,
  "allocated_memory_gib": 1.5,
  "created_at": "2026-08-31T14:22:05Z",
  "expires_at": "2026-08-31T14:22:05Z",
  "max_expires_at": "2026-08-31T14:22:05Z",
  "max_lifetime_seconds": 250,
  "remaining_extend_seconds": 250,
  "lifetime_used_seconds": 250,
  "lifetime_used_percent": 7.5,
  "startup_metrics": {
    "total_ms": 250,
    "pod_creation_ms": 250,
    "pod_ready_ms": 250,
    "phases": [
      {
        "name": null,
        "durationMs": null
      }
    ]
  }
}