Skip to content
Hayonix

API reference · Sandboxes

Create a sandbox (launch gate and quotas apply); it ends by itself at its deadline

POST/v1/sandboxes
API keysandbox:createProjectIdempotency-Key
TypeScript
client.sandboxes.create()
Python
client.sandboxes.create()
CLI
hayonix sandboxes create

The sandbox starts at once and is billed per second from when it starts, at its size’s price. It ends at lifetime_seconds (extendable), after idle_timeout_seconds without a run or a file operation, or when ended. Nothing in it survives its end.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the sandbox:create permission (a key's scope, or a role that includes it).

Examples

The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.

curl -sS "$API_BASE_URL/sandboxes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "agent scratch",
  "size": "cpu-2c-4gb",
  "region": "dev-local-1",
  "lifetime_seconds": 3600
}'

Request

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.
Idempotency-KeynoMakes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you.

Body

JSON (application/json): CreateSandboxRequest.

  • namestring

    Its name

    up to 100 characters

  • sizestring

    One of cpu-2c-4gb, cpu-4c-16gb, cpu-8c-32gb (default cpu-2c-4gb)

  • regionstringrequired

    Region code

    1–64 characters

  • lifetime_secondsinteger

    How long it lives unless extended (default 3600)

    60–86400

  • idle_timeout_secondsinteger

    It ends after this long without a run or a file operation (default 900)

    60–86400

  • metadataobject

    Your own key/value labels, returned as given

Response

201 Sandbox — The new sandbox (starting)

  • objectstringrequired

    Always `sandbox`: the type of this object

    One ofsandbox

  • idstringrequired

    Unique ID (`sbx_…`)

    ID with prefix sbx_

  • org_idstringrequired

    Organization it belongs to

    ID with prefix org_

  • project_idstringrequired

    Project it belongs to

    ID with prefix prj_

  • namestringrequired

    Its name

  • statusSandboxStatusrequired
    Show 4 fields of status
    • statestringrequired

      starting | ready (waiting for code) | busy (running code) | unreachable (its host stopped reporting) | ending | ended | failed

      One ofstartingreadybusyunreachableendingendedfailed

    • reasonstringrequired

      Machine-readable cause, lower_snake_case

    • messagestringrequired

      One sentence for people

    • sincestring (date-time)required

      When it entered this state (ISO 8601, UTC)

  • sizeobjectrequired

    The size it was created with

    Show 4 fields of size
    • codestringrequired

      Machine-readable code

    • display_namestring | nullrequired

      Name to show people

    • vcpusinteger | nullrequired

      Virtual CPUs (null if the size is no longer listed)

    • memory_gbinteger | nullrequired

      Memory in GB (null if the size is no longer listed)

  • regionstringrequired

    Region code

  • priceobjectrequired

    Its price, fixed when it was created

    Show 2 fields of price
    • per_secondstringrequired

      Price per second of running, nano-USD (what is billed)

      pattern ^-?[0-9]+$

    • per_hourstringrequired

      The same price per hour (per_second × 3600), nano-USD

      pattern ^-?[0-9]+$

  • usageobjectrequired

    What it has cost so far

    Show 2 fields of usage
    • billed_secondsstringrequired

      Running time billed so far, in seconds (decimal string)

    • cost_so_farstringrequired

      Cost of that running time, nano-USD; can lag a few seconds behind

      pattern ^-?[0-9]+$

  • lifetimeobjectrequired

    When it ends, and what keeps it alive

    Show 5 fields of lifetime
    • expires_atstring (date-time)required

      When it ends by itself

    • idle_timeout_secondsintegerrequired

      It ends after this many seconds without a run or a file operation

    • idle_expires_atstring (date-time) | nullrequired

      When the idle timeout ends it if nothing runs and no file is touched before then (null once ended)

    • last_activity_atstring (date-time)required

      Time last activity (ISO 8601, UTC)

    • max_expires_atstring (date-time)required

      The latest an extension can reach

  • runsobjectrequired

    Run counts

    Show 2 fields of runs
    • activeintegerrequired

      Runs queued or running now

    • totalintegerrequired

      Runs sent to it over its life, in any state

  • metadataobjectrequired

    Your own key/value labels, returned as given

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • started_atstring (date-time) | nullrequired

    When it first started running

  • ended_atstring (date-time) | nullrequired

    When it ended (null until then) (ISO 8601, UTC)

  • end_reasonstring | nullrequired

    requested | expired | idle | billing | suspended | host_maintenance | host_lost | failed

    One ofrequestedexpiredidlebillingsuspendedhost_maintenancehost_lostfailed

Example response
Example response
{
  "object": "sandbox",
  "id": "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "name": "string",
  "status": {
    "state": "starting",
    "reason": "string",
    "message": "string",
    "since": "2026-01-01T00:00:00.000Z"
  },
  "size": {
    "code": "cpu-2c-4gb",
    "display_name": "string",
    "vcpus": 1,
    "memory_gb": 1
  },
  "region": "string",
  "price": {
    "per_second": "1500000000",
    "per_hour": "1500000000"
  },
  "usage": {
    "billed_seconds": "string",
    "cost_so_far": "1500000000"
  },
  "lifetime": {
    "expires_at": "2026-01-01T00:00:00.000Z",
    "idle_timeout_seconds": 1,
    "idle_expires_at": "2026-01-01T00:00:00.000Z",
    "last_activity_at": "2026-01-01T00:00:00.000Z",
    "max_expires_at": "2026-01-01T00:00:00.000Z"
  },
  "runs": {
    "active": 1,
    "total": 1
  },
  "metadata": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "started_at": "2026-01-01T00:00:00.000Z",
  "ended_at": "2026-01-01T00:00:00.000Z",
  "end_reason": "requested"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
402insufficient_credit_errorThe organization is out of credit or over a spend limit.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429quota_exceeded_error quota_exceededAn organization quota is reached; param names it.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.