Create a sandbox

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

Authorization

AuthorizationBearer token (ibk_<public id>_<secret>) · headerrequired

A lane's API key. The lane is taken from the key, never from the request.

Header parameters

Idempotency-Keystring

Makes a retry safe. A retry with the same key and body gets the answer described for this operation; the same key with a different body gets 409 idempotency_mismatch. Keys are kept for 24 hours. The SDKs send a fresh key on every call they may retry.

min length 1 · max length 255

Request body

requiredapplication/json

imagestring

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.

max length 64 · matches ^img_[0-9A-Za-z]+$

lifetime_msinteger

How long the sandbox may live, in milliseconds. At most 300000; 120000 when absent.

min 1 · max 300000 · default: 120000

namestring

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.

matches ^[a-z0-9-]{1,63}$

regionstring

The region the caller expects. Region is a lane setting; if this differs from the lane's, the create gets 400 region_mismatch.

min length 1 · max length 32

resourcesResourceRequest

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.

Show properties

cpunumber

CPU cores requested. Fractions are allowed.

cpu_limitnumber

CPU cores the sandbox may use at most. At least cpu.

memory_limit_mibinteger

Memory the sandbox may use at most, in MiB. At least memory_mib.

min 1

memory_mibinteger

Memory requested, in MiB.

min 1

storeStoreRequest

A read-only folder of the lane's store, attached at create. A lane with no store folder attached gets 409 store_unavailable.

Show properties

key_prefixstringrequired

A prefix in the lane's store folder, relative to the lane's root prefix: no leading /, ends in /, no . or .. segment. The platform may still refuse it with 400 store_prefix_refused.

min length 2 · max length 512 · matches ^(?:[A-Za-z0-9._-]+\/)+$

mount_pathstringrequired

Where the folder appears in the sandbox: an absolute path inside workdir.

min length 1 · max length 4096 · matches ^\/

workdirstringrequired

The working directory, an absolute path. It is made at create.

min length 1 · max length 4096 · matches ^\/

Responses

201

The sandbox.

created_atstring<date-time>required

A UTC time in RFC 3339 form.

idstringrequired

The sandbox id, sbx_....

lifetime_msintegerrequired

namestring | nullrequired

The caller's name, or null.

regionstringrequired

resourcesResourcesrequired

The CPU and memory in effect, after lane defaults.

Show properties

cpunumberrequired

cpu_limitnumberrequired

memory_limit_mibintegerrequired

memory_mibintegerrequired

statusSandboxStatusrequired

pending while the create is in flight, running once it can take calls, stopped once its lifetime or size limit was reached or it was removed. A create that fails leaves no sandbox, so a later GET answers 404.

Allowed:pendingrunningstopped

storeStore | nullrequired

The attached store folder, or null when none was asked for.

Show properties

Any of:

object

key_prefixstringrequired

mount_pathstringrequired

null

null

workdirstringrequired

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.

errorErrorDetailrequired

Show properties

codestringrequired

A stable, machine-readable code. Known codes: env_name_refused, file_not_found, file_too_large, idempotency_mismatch, image_not_built, in_progress, internal_error, invalid_request, lane_limit, name_in_use, not_found, payload_too_large, resources_over_cap, region_mismatch, sandbox_stopped, unavailable, store_prefix_refused, store_unavailable, unauthorized. New codes may be added, so treat an unknown one by its HTTP status.

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

401

unauthorized: The API key is missing, unknown or revoked.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

404

not_found: No such resource in this key's lane. Another lane's ids are not found either.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

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.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

429

lane_limit: The lane already runs its maximum number of sandboxes.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

500

internal_error: The platform failed. A retry may succeed; for a call that creates or writes, retry with the same Idempotency-Key.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

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.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

Request

curl -X POST 'https://api.ibby.ai/v1/sandboxes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "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"
}'

const response = await fetch("https://api.ibby.ai/v1/sandboxes", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"image\": \"img_4Rt8sK\",\n  \"lifetime_ms\": 120000,\n  \"name\": \"yb-run-4f2a\",\n  \"region\": \"au\",\n  \"resources\": {\n    \"cpu\": 1,\n    \"cpu_limit\": 1,\n    \"memory_limit_mib\": 1,\n    \"memory_mib\": 1\n  },\n  \"store\": {\n    \"key_prefix\": \"runs/2026-11-14/\",\n    \"mount_path\": \"/work/in\"\n  },\n  \"workdir\": \"/work\"\n}"
});

import requests

response = requests.post(
    "https://api.ibby.ai/v1/sandboxes",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"image\": \"img_4Rt8sK\",\n  \"lifetime_ms\": 120000,\n  \"name\": \"yb-run-4f2a\",\n  \"region\": \"au\",\n  \"resources\": {\n    \"cpu\": 1,\n    \"cpu_limit\": 1,\n    \"memory_limit_mib\": 1,\n    \"memory_mib\": 1\n  },\n  \"store\": {\n    \"key_prefix\": \"runs/2026-11-14/\",\n    \"mount_path\": \"/work/in\"\n  },\n  \"workdir\": \"/work\"\n}",
)

Response

{
  "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"
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}