Sandboxes

Core CRUD and lookup for sandbox microVMs.

At a glance

• Base URL: https://api.sb.createos.sh
• Auth: X-Api-Key: <token> header. Get a token
• Response envelope: JSend, {"status": "...", "data": ...}

Sandbox status lifecycle

A sandbox moves through these statuses:

POST /v1/sandboxes

Create a new sandbox. Time to the first command depends on the image, available capacity, and host load.

Auth required: Yes

Request body

When enabled for the account, an unpinned ordinary create can fall back from eu to us (or vice versa) after a capacity rejection. Explicit region/host placement, disks, networks and snapshot restores prevent this fallback. Check the returned sandbox region; set region explicitly when location matters.

Note: bandwidth_quota_bytes is not settable at create time. Each sandbox starts with a deployment-configured allowance; the software default is 50 GiB. Read /bandwidth for your sandbox's actual quota and use POST /v1/sandboxes/{id}/bandwidth/recharge to increase it once the sandbox is running.

Snapshots and labels

Use snapshot_id to restore an owned ready snapshot; it cannot be combined with rootfs. Disk size defaults to the captured size. Disk snapshots may grow to an allowed size, but cannot shrink; full snapshots require the captured CPU, memory and disk size.

The optional labels object stores string key/value metadata, for example {"team":"backend","environment":"test"}. Labels are returned in sandbox views. Limits: 100 entries, non-empty keys up to 128 bytes, values up to 1,024 bytes, and 65,536 bytes total including overhead. Keys and values cannot contain NUL bytes. Labels are metadata, not secrets or placement selectors.

Example request

curl -X POST https://api.sb.createos.sh/v1/sandboxes \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shape": "s-1vcpu-1gb",
    "rootfs": "devbox:1",
    "name": "my-sandbox",
    "ingress_enabled": true,
    "auto_pause_after_seconds": 600,
    "ssh_pubkeys": ["ssh-ed25519 AAAA..."],
    "envs": { "ANTHROPIC_API_KEY": "sk-ant-..." },
    "egress": ["pypi.org", "1.1.1.1:53"]
  }'

Example response

{
  "status": "success",
  "data": {
    "id": "sb-01K...",
    "name": "my-sandbox",
    "ip": "192.168.0.12",
    "shape": "s-1vcpu-1gb",
    "rootfs": "devbox:1",
    "vcpu": 1,
    "mem_mib": 1024,
    "disk_mib": 10240,
    "spawn_ms": 87.4,
    "egress": ["pypi.org", "1.1.1.1:53"],
    "bandwidth_quota_bytes": 53687091200
  }
}

Notable errors: 400 invalid body or disabled rootfs, 503 no host capacity.

GET /v1/sandboxes

List sandboxes owned by the caller (paginated).

Auth required: Yes

Query parameters

Example request

curl "https://api.sb.createos.sh/v1/sandboxes?status=running&limit=10" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Example response

{
  "status": "success",
  "data": {
    "data": [
      {
        "id": "sb-01K...",
        "name": "my-sandbox",
        "status": "running",
        "ip": "192.168.0.12",
        "vcpu": 1,
        "mem_mib": 1024,
        "disk_mib": 10240,
        "shape": "s-1vcpu-1gb",
        "rootfs": "devbox:1",
        "region": "eu",
        "ingress_enabled": true,
        "auto_pause_after_seconds": 600,
        "created_at": "2026-06-17T08:00:00Z"
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 10,
      "offset": 0,
      "count": 1
    }
  }
}

GET /v1/sandboxes/{id}

Get details for a single sandbox.

Auth required: Yes

Path parameters

Example request

curl https://api.sb.createos.sh/v1/sandboxes/sb-01K... \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Example response

{
  "status": "success",
  "data": {
    "id": "sb-01K...",
    "name": "my-sandbox",
    "status": "running",
    "ip": "192.168.0.12",
    "vcpu": 1,
    "mem_mib": 1024,
    "disk_mib": 10240,
    "shape": "s-1vcpu-1gb",
    "rootfs": "devbox:1",
    "region": "eu",
    "ingress_enabled": true,
    "bandwidth_ingress_bytes": 1048576,
    "auto_pause_after_seconds": 600,
    "envs": ["ANTHROPIC_API_KEY"],
    "ssh_pubkeys": ["ssh-ed25519 AAAA..."],
    "egress": ["pypi.org"],
    "created_at": "2026-06-17T08:00:00Z",
    "running_at": "2026-06-17T08:00:01Z"
  }
}

Notable errors: 404 sandbox not found.

envs returns only the key names; values are never exposed via the API.

Lifecycle fields such as paused_at, last_resumed_at, and forked_from are omitted when unset.

PATCH /v1/sandboxes/{id}

Partially update a sandbox. Only fields you include are changed. labels merges supplied key/value pairs into the existing map; matching keys are overwritten and other labels remain. An empty map does not clear labels. The merged map must meet the limits above. Capture conflicts return 409; wait for the capture to release the source before retrying.

curl -G https://api.sb.createos.sh/v1/sandboxes \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  --data-urlencode 'labels={"team":"backend"}'
 
curl -X PATCH "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID" \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labels":{"environment":"production"}}'

Auth required: Yes

Path parameters

Request body

Example request

curl -X PATCH https://api.sb.createos.sh/v1/sandboxes/sb-01K... \
  -H "X-Api-Key: $CREATEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ingress_enabled": false, "auto_pause_after_seconds": 1800}'

Example response

Returns the full updated SandboxView object (same shape as GET).

Notable errors: 400 invalid values, 404 not found.

DELETE /v1/sandboxes/{id}

Destroy a sandbox permanently.

Auth required: Yes

Path parameters

Example request

curl -X DELETE https://api.sb.createos.sh/v1/sandboxes/sb-01K... \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Example response

{
  "status": "success",
  "data": {
    "id": "sb-01K...",
    "status": "destroying"
  }
}

Idempotent: deleting an already-destroyed sandbox returns the same shape with status: "destroyed". A fresh delete returns "destroying" and completes within a few seconds.

Notable errors: 404 not found.

GET /v1/sandboxes/by-ip/{ip}

Look up a sandbox by its VM IP address.

Auth required: Yes

Path parameters

Example request

curl https://api.sb.createos.sh/v1/sandboxes/by-ip/192.168.0.12 \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Example response

Returns a SandboxView object (same shape as GET /v1/sandboxes/{id}).

Notable errors: 404 no sandbox found with that IP.