# Create a sandbox, optionally from a template, and optionally queue it

`POST /v1/sandboxes`

**In this build:** Works on the simulator or a real VM.

**Scope:** `sandbox.create`

**CLI:** `harebox new`

Send an `Idempotency-Key` header. A retry with the same key never repeats the action.

## Request: `CreateSandboxRequest`

| Field | Type | Notes |
|---|---|---|
| `name` | `string` |  |
| `size` | `Size` |  |
| `tier` | `Tier` |  |
| `region` | `Region` |  |
| `image` | `string` | One of: `ubuntu-24.04` |
| `template` | `string` | Template name, name@version, or share code. |
| `project` | `string` |  |
| `fleet` | `string` |  |
| `labels` | `Labels` |  |
| `environment` | `string` |  |
| `no_env` | `boolean` | Pass nothing of yours into the sandbox. Use for third-party tenants. |
| `env` | `object` |  |
| `setup_script` | `string` |  |
| `files` | `array` |  |
| `sleep` | `SleepPolicy` |  |
| `ttl_seconds` | `integer or null` | Auto-stop this long after creation or the last resume. Omit for one hour; null for none. The trial requires 7200 or less. A running agent prompt moves the deadline. |
| `snapshots` | `boolean` | False for no saved state. |
| `monitoring` | `boolean` |  |
| `visibility` | `string` | One of: `private`, `shared` |
| `endpoints` | `array` |  |
| `placement` | `string` | wait for capacity, answer in about a second, or join the start queue. One of: `wait`, `fail_fast`, `queue` |
| `queue_deadline_seconds` | `integer` |  |

## Response: 202

`Sandbox`

| Field | Type | Notes |
|---|---|---|
| `id` (required) | `string` |  |
| `name` | `string` |  |
| `state` (required) | `LifecycleState` |  |
| `conditions` (required) | `array` |  |
| `condition_details` | `object` | Why each condition applies, and for sleep, what is keeping the sandbox awake. |
| `region` (required) | `Region` |  |
| `tier` (required) | `Tier` |  |
| `size` (required) | `Size` |  |
| `image` | `string` | Base image: ubuntu-24.04. |
| `location` | `object` | Where the sandbox runs now. Read-only: HareBox places sandboxes itself and may move them on resume. |
| `created_by` | `string` | The API key that created this sandbox. A key's monthly budget counts what it created. |
| `project` | `string or null` |  |
| `fleet` | `string or null` |  |
| `labels` | `Labels` |  |
| `environment` | `object or null` |  |
| `template` | `string or null` |  |
| `forked_from` | `string or null` |  |
| `ipv4` | `string or null` |  |
| `ipv6` | `string or null` |  |
| `subdomain` | `string` |  |
| `sleep` | `SleepPolicy` |  |
| `deadline` | `string or null` | Absolute stop time. Null means none. |
| `visibility` | `string` | One of: `private`, `shared` |
| `capabilities` (required) | `object` | What this sandbox can do right now. Agents should check these rather than infer them. |
| `hydration` | `object or null` |  |
| `simulated` | `boolean` | True when the machine is the labelled simulator rather than a real VM. |
| `fork_ids` | `array` | All new sandboxes, when a fork asked for a count. |
| `meter` | `object` |  |
| `created_at` (required) | `string` |  |
| `ready_at` | `string or null` |  |

Errors follow [one format](../errors.html).