---
title: "Create a sandbox"
method: POST
path: "/sandboxes"
tags: ["Sandboxes"]
---

# Create a sandbox

`POST /sandboxes`

## Request

- Base URL: `https://sandbox-as-a-service.com/v1`
- URL: `https://sandbox-as-a-service.com/v1/sandboxes`
- Auth: HTTP bearer

Provisions a sandbox and returns once it is ready to accept commands. Pass an `Idempotency-Key` header to make retries safe: repeating a request with the same key returns the original sandbox instead of creating a second one.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `size` 'small' | 'medium' | 'large': small: 2 vCPU, 4 GB RAM, 40 GB disk; medium: 4 vCPU, 8 GB RAM, 80 GB disk; large: 8 vCPU, 16 GB RAM, 160 GB disk
  - `name` string: Optional label for your own reference.
  - `timeout_minutes` integer: The sandbox is destroyed automatically after this many minutes.
  - `snapshot_id` string: Restore this snapshot into a new sandbox instead of booting a fresh one. The snapshot must be `available`, and the new sandbox boots from its captured image with the size the snapshot was taken at — omit `size` for that, or pass `size` matching it. The captured filesystem is restored; processes are not. Billing, capacity and concurrency checks apply as for any other create.

## Response `200`

An existing sandbox was returned because the idempotency key was reused.

- Sandbox
  - `object` 'sandbox'
  - `id` string
  - `name` string, nullable
  - `status` 'provisioning' | 'running' | 'deleting' | 'deleted' | 'failed': Lifecycle state. Commands can only run while the sandbox is `running`.
  - `size` 'small' | 'medium' | 'large'
  - `resources` object
    - `vcpu` integer
    - `memory_gb` integer
    - `disk_gb` integer
  - `timeout_minutes` integer
  - `created_at` string, date-time
  - `ready_at` string, date-time, nullable
  - `expires_at` string, date-time, nullable
  - `deleted_at` string, date-time, nullable

## Other responses

- `201`: Sandbox created and ready.
- `400`: Invalid request parameters.
- `401`: Missing or invalid API key.
- `402`: Insufficient credit balance.
- `403`: Account suspended.
- `404`: No snapshot with that id for this account.
- `409`: Snapshot capture is still in progress.
- `429`: Rate limit or concurrent sandbox limit reached.
- `503`: Capacity temporarily unavailable — retry shortly.

---

[API](https://skmtc.dev/sandbox-as-a-service/apis/sandbox-as-a-service-api.md) · [All operations](https://skmtc.dev/sandbox-as-a-service/apis/sandbox-as-a-service-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sandbox-as-a-service/apis/sandbox-as-a-service-api/revisions/4f1ea2cf8333?raw)