---
search:
  tags:
    - Sandboxes
    - POST
seo:
  description: >-
    Creates a sandbox with no network, no secrets and a time limit. A retry with
    the same… Reference for the POST /v1/sandboxes endpoint in the Ibby API.
sidebar:
  label: Create a sandbox
  badge: POST
title: Create a sandbox
type: openapi-operation
---
Creates a sandbox with no network, no secrets and a time limit. A retry with the same `Idempotency-Key` returns the same sandbox, also with 201.

`POST /v1/sandboxes`

**Request body** (`application/json`, required)

- `image` (string) — The image to create the sandbox from, an \`img\_\` id of this lane that is \`ready\`. When absent, the lane's default image. An image that is not ready gets 409 \`image\_not\_built\`; an unknown one gets 404 \`not\_found\`.
- `lifetime_ms` (integer) — How long the sandbox may live, in milliseconds. At most 300000; 120000 when absent.
- `name` (string) — A name the caller chooses: lowercase letters, digits and dashes, up to 63 characters. No two pending or running sandboxes in a lane share a name; a stopped or removed sandbox's name may be used again. Used to remove the sandbox by name after a crash.
- `region` (string) — The region the caller expects. Region is a lane setting; if this differs from the lane's, the create gets 400 \`region\_mismatch\`.
- `resources` (ResourceRequest) — CPU and memory for the sandbox. Each value is optional; the lane's default fills any gap. A value above the lane's cap is refused with 400 \`resources\_over\_cap\`.
- `store` (StoreRequest) — A read-only folder of the lane's store, attached at create. A lane with no store folder attached gets 409 \`store\_unavailable\`.
- `workdir` (string, required) — The working directory, an absolute path. It is made at create.

Request body example:

```json
{
  "image": "img_4Rt8sK",
  "lifetime_ms": 120000,
  "name": "yb-run-4f2a",
  "region": "au",
  "resources": {
    "cpu": 1,
    "cpu_limit": 1,
    "memory_limit_mib": 1,
    "memory_mib": 1
  },
  "store": {
    "key_prefix": "runs/2026-11-14/",
    "mount_path": "/work/in"
  },
  "workdir": "/work"
}
```

**Responses**

- `201` — The sandbox.
- `400` — \`invalid\_request\`: The request does not match the contract. \`region\_mismatch\`: \`region\` differs from the lane's region. \`resources\_over\_cap\`: A \`resources\` value is above the lane's cap. \`store\_prefix\_refused\`: The store \`key\_prefix\` is not allowed for this lane.
- `401` — \`unauthorized\`: The API key is missing, unknown or revoked.
- `404` — \`not\_found\`: No such resource in this key's lane. Another lane's ids are not found either.
- `409` — \`in\_progress\`: A call with this \`Idempotency-Key\` is still running, or the sandbox is still being created. Retry later. \`idempotency\_mismatch\`: The \`Idempotency-Key\` was used before with a different body. \`name\_in\_use\`: A pending or running sandbox in this lane already has this name. A stopped or removed sandbox's name may be used again. \`image\_not\_built\`: The image is not ready. On a create: its build is still running, or it failed; check the image, then create the sandbox again. On getting an image: the image has no build on the lane's current provider; rebuild it. That arises only after a lane changes provider. \`store\_unavailable\`: This lane has no store folder attached.
- `429` — \`lane\_limit\`: The lane already runs its maximum number of sandboxes.
- `500` — \`internal\_error\`: The platform failed. A retry may succeed; for a call that creates or writes, retry with the same Idempotency-Key.
- `503` — \`unavailable\`: A service behind the API could not be reached. Retry after a short wait; for a call that creates or writes, with the same Idempotency-Key.

Response example, 201:

```json
{
  "created_at": "2019-08-24T14:15:22Z",
  "id": "sbx_7Hc2mQ",
  "lifetime_ms": 0,
  "name": "string",
  "region": "string",
  "resources": {
    "cpu": 0,
    "cpu_limit": 0,
    "memory_limit_mib": 0,
    "memory_mib": 0
  },
  "status": "pending",
  "store": {
    "key_prefix": "string",
    "mount_path": "string"
  },
  "workdir": "string"
}
```