Skip to content
Hayonix

API reference · Sandboxes

Run code in the sandbox and wait for the result (or stream it)

POST/v1/sandboxes/{sandbox_id}/runs
API keysandbox:updateProjectIdempotency-Key
TypeScript
client.sandboxes.runCode()
Python
client.sandboxes.run_code()
CLI
hayonix sandboxes run

Python runs share one interpreter per sandbox, so variables, imports and functions persist between runs; JavaScript and shell runs each start a fresh process. Files in the workspace persist for the sandbox’s life whatever the language. A run started right after the sandbox was created waits for it to be ready. By default the call answers once the run has finished, with all of its output (up to its cap); wait=false answers at once with the queued run (follow it with GET …/runs/{run_id}/events), and stream=true answers with that event stream directly. A retry with the same Idempotency-Key never runs the code twice.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the sandbox:update 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/sbx_01jc5zq4m8k3v6x9t2w7r0b1e4/runs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "language": "python",
  "code": "x = 21 * 2\nprint(x)",
  "timeout_seconds": 30
}'

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.

Path parameters

  • sandbox_idstringrequired

    ID of the sandbox

    ID with prefix sbx_

Query parameters

  • waitboolean | string

    true (default): answer when the run has finished. false: answer at once with the queued run; follow it with GET …/runs/{run_id}/events

  • streamboolean | string

    true: answer with the run’s events as a server-sent event stream (the same events as GET …/runs/{run_id}/events)

Body

JSON (application/json): RunCodeRequest.

  • languagestringrequired

    python (one interpreter per sandbox: state persists between runs), javascript (Node, a fresh process per run) or shell (bash, a fresh process per run)

    One ofpythonjavascriptshell

  • codestringrequired

    Machine-readable code

  • stdinstring

    Given to the code on standard input

  • timeout_secondsinteger

    Time limit (default 60)

    1–900

  • max_output_bytesinteger

    stdout + stderr cap; the run is cut off past it (default 1048576)

    1024–4194304

Response

201 SandboxRun — The run (finished, unless wait=false), or its events with stream=true

  • objectstringrequired

    Always `sandbox_run`: the type of this object

    One ofsandbox_run

  • idstringrequired

    Unique ID (`sbr_…`)

    ID with prefix sbr_

  • sandbox_idstringrequired

    ID of the sandbox

    ID with prefix sbx_

  • languagestringrequired

    Language the code ran as

    One ofpythonjavascriptshell

  • statestringrequired

    queued | running | completed (it ran: see exit_code and cut_off) | error (it could not run: see error)

    One ofqueuedrunningcompletederror

  • outcomestring | nullrequired

    One word for how it ended (null while queued or running)

    One ofsucceededfailedtime_limitoutput_limitout_of_memorycancelledsandbox_endederror

  • exit_codeinteger | nullrequired

    Exit status of the code (0 means success); null until it finishes, or when it could not run

  • cut_offstring | nullrequired

    Why it was stopped before it finished: time_limit | output_limit | out_of_memory | cancelled | sandbox_ended

    One oftime_limitoutput_limitout_of_memorycancelledsandbox_ended

  • state_resetbooleanrequired

    The Python interpreter had to be restarted: variables from earlier runs are gone

  • errorstring | nullrequired

    Why the run could not run or was stopped, for people; null otherwise

  • stdoutstringrequired

    Standard output (see `output.truncated`)

  • stderrstringrequired

    Standard error (see `output.truncated`)

  • outputobjectrequired

    How much output the run produced

    Show 3 fields of output
    • stdout_bytesintegerrequired

      Bytes the run wrote to standard output

    • stderr_bytesintegerrequired

      Bytes the run wrote to standard error

    • truncatedbooleanrequired

      stdout and stderr above are the run's whole output (up to its cap) in the response to the run itself, and the first 65536 bytes of each in the record kept for 7 days after the sandbox ends; true when this copy is shorter than what the run produced

  • codestringrequired

    Machine-readable code

  • timeout_secondsintegerrequired

    Time limit the run had, in seconds

  • max_output_bytesintegerrequired

    Cap on stdout plus stderr the run had, in bytes

  • duration_msinteger | nullrequired

    How long it ran, in milliseconds; null until it finishes

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • started_atstring (date-time) | nullrequired

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

  • finished_atstring (date-time) | nullrequired

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

Example response
Example response
{
  "object": "sandbox_run",
  "id": "sbr_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "sandbox_id": "sbx_01jc5zq4m8k3v6x9t2w7r0b1e4",
  "language": "python",
  "state": "queued",
  "outcome": "succeeded",
  "exit_code": 1,
  "cut_off": "time_limit",
  "state_reset": true,
  "error": "string",
  "stdout": "string",
  "stderr": "string",
  "output": {
    "stdout_bytes": 1,
    "stderr_bytes": 1,
    "truncated": true
  },
  "code": "string",
  "timeout_seconds": 1,
  "max_output_bytes": 1,
  "duration_ms": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "started_at": "2026-01-01T00:00:00.000Z",
  "finished_at": "2026-01-01T00:00:00.000Z"
}

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.
404not_found_errorNo such resource in this project (an ID from another project is answered the same way).
409conflict_errorThe resource's current state does not allow this.
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.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.