> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new sandbox

> Sandbox created successfully

### Request body

`CreateSandboxRequest`

<ParamField body="session_id" type="string (uuid)" />

<ParamField body="cpus" type="string" />

<ParamField body="memory" type="string" />

<ParamField body="isolation" type="string" />

<ParamField body="timeout_seconds" type="integer" />

<ParamField body="env" type="object" />

<ParamField body="gpu" type="object" />

<ParamField body="image" type="string" />

<ParamField body="desktop_os" type="string" required />

### Response

`SandboxResponse`

<ResponseField name="sandbox_id" type="string (uuid)" required>
  Unique sandbox identifier
</ResponseField>

<ResponseField name="org_id" type="string" required>
  Organization that owns this sandbox
</ResponseField>

<ResponseField name="session_id" type="string" required>
  Session identifier
</ResponseField>

<ResponseField name="status" type="string" required>
  Current sandbox status
</ResponseField>

<ResponseField name="pod_ip" type="string">
  Internal pod IP address
</ResponseField>

<ResponseField name="sandbox_epoch" type="integer" required>
  Sandbox recycle epoch counter
</ResponseField>

<ResponseField name="allocated_vcpu" type="number">
  Allocated vCPU cores
</ResponseField>

<ResponseField name="allocated_memory_gib" type="number">
  Allocated memory in GiB
</ResponseField>

<ResponseField name="created_at" type="string (date-time)" required>
  ISO 8601 creation timestamp
</ResponseField>

<ResponseField name="expires_at" type="string (date-time)" required>
  ISO 8601 expiration timestamp
</ResponseField>

<ResponseField name="max_expires_at" type="string (date-time)" required>
  Maximum possible expiration
</ResponseField>

<ResponseField name="max_lifetime_seconds" type="integer" required>
  Maximum sandbox lifetime in seconds
</ResponseField>

<ResponseField name="remaining_extend_seconds" type="integer" required>
  Seconds available for extension
</ResponseField>

<ResponseField name="lifetime_used_seconds" type="integer" required>
  Seconds of lifetime consumed
</ResponseField>

<ResponseField name="lifetime_used_percent" type="number" required>
  Percentage of lifetime consumed
</ResponseField>

<ResponseField name="startup_metrics" type="object">
  Startup timing breakdown

  <Expandable title="startup_metrics">
    <ResponseField name="total_ms" type="number" required>
      Total startup time in milliseconds
    </ResponseField>

    <ResponseField name="pod_creation_ms" type="number" required>
      Pod creation time
    </ResponseField>

    <ResponseField name="pod_ready_ms" type="number" required>
      Time until pod ready
    </ResponseField>

    <ResponseField name="phases" type="object[]" required>
      <Expandable title="phases">
        <ResponseField name="name" type="string" required />

        <ResponseField name="durationMs" type="number" required />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### 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                |

<RequestExample>
  ```bash cURL theme={null}
  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"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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
        }
      ]
    }
  }
  ```
</ResponseExample>