Skip to content
Ibby docs
Esc
↑↓navigate↵open⌘Jpreview

Run a command

Runs a command and waits for it, up to timeout_ms. A retry with the same Idempotency-Key gets 409 in_progress while the command runs, and the outcome with stdout null once it has finished.

POST/v1/sandboxes/{id}/exec
Authorization
AuthorizationBearer token (ibk_<public id>_<secret>) · headerrequired

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

Path parameters
idstringrequired

A sandbox id: sbx_ and a random part, at most 64 characters.

max length 64 · matches ^sbx_[0-9A-Za-z]+$
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
commandstring[]required

The program and its arguments, as an argv array. No shell runs unless the caller runs one.

min items 1
cwdstring

The directory to run in. Defaults to the sandbox's workdir.

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

Up to 8 environment variables. A name that looks like a secret is refused with 400 env_name_refused.

timeout_msinteger

How long the command may run, in milliseconds. At most 120000, and that when absent. When it passes, the result is timed_out.

min 1 · max 120000 · default: 120000
Responses
200

The command ended or timed out.

One of:
ExecExited
exit_codeintegerrequired

The command's exit code.

outcomestringrequired
stdoutstring | nullrequired

Standard output, cut at the lane's cap (default 64 KiB). Null when the output is unavailable: a replayed exec (a retry of a finished command with the same Idempotency-Key, which returns the outcome but not the output, because the platform keeps no output), or a timed-out one in this version. stdout_truncated is false whenever stdout is null.

stdout_truncatedbooleanrequired

True when stdout was cut at the lane's cap.

ExecTimedOut
outcomestringrequired
stdoutstring | nullrequired

Standard output, cut at the lane's cap (default 64 KiB). Null when the output is unavailable: a replayed exec (a retry of a finished command with the same Idempotency-Key, which returns the outcome but not the output, because the platform keeps no output), or a timed-out one in this version. stdout_truncated is false whenever stdout is null.

stdout_truncatedbooleanrequired

True when stdout was cut at the lane's cap.

400

invalid_request: The request does not match the contract. env_name_refused: An env name looks like a secret, which a sandbox may not receive.

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

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.

404

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

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.

409

sandbox_stopped: The sandbox has stopped: its lifetime or size limit was reached, or it was removed. 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.

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.

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

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.

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

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.

Request
curl -X POST 'https://api.ibby.ai/v1/sandboxes/sbx_7Hc2mQ/exec' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "command": [
    "python",
    "-c",
    "print(1)"
  ],
  "cwd": "string",
  "env": {
    "property1": "string",
    "property2": "string"
  },
  "timeout_ms": 120000
}'
Response
{
  "exit_code": 0,
  "outcome": "exited",
  "stdout": "string",
  "stdout_truncated": true
}

Was this page helpful?