Skip to content
DashboardGet API key

Run a command

View .md
POST

Run a shell command in the sandbox, in /home/user unless cwd says otherwise.

Synchronous by default: the response carries the exit code and output, waiting up to timeoutSeconds (max 120). Set background for anything longer: the response is 202 with a command id to poll.

A command is never retried: if the call fails mid-way, the command may still be running. Not available with test-mode keys.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • sandboxIdstringrequired

    Sandbox ID.

Body

application/json

  • commandstringrequired

    Run with a shell, so pipes and && work.

    Limitsmax length 65536
  • cwdstring

    Working directory, relative to /home/user.

  • timeoutSecondsinteger

    For a synchronous command: how long to wait before it is killed and timedOut is true. Use background for anything longer.

    Default30
    Limitsmin 1 · max 120
  • backgroundboolean

    Start it and return a command id at once. Read its status and output with GET /v1/sandboxes/{sandboxId}/commands/{commandId}.

    Defaultfalse

Responses

200The command finished, or was killed at its timeout. `result` is set.
  • resultobject
    8 properties
    • exitCodeintegerrequirednullable

      Null when the command was killed.

    • stdoutstringrequired
    • stderrstringrequired
    • stdoutTruncatedbooleanrequired
    • stderrTruncatedbooleanrequired
    • timedOutbooleanrequired
    • startedAtstring<date-time>nullable
    • finishedAtstring<date-time>nullable
  • commandobject
    2 properties
    • idstringrequired

      Pass it to GET /v1/sandboxes/{sandboxId}/commands/{commandId}.

    • statusstringrequired
      One ofrunning
202Started in the background. `command` is set.
  • resultobject
    8 properties
    • exitCodeintegerrequirednullable

      Null when the command was killed.

    • stdoutstringrequired
    • stderrstringrequired
    • stdoutTruncatedbooleanrequired
    • stderrTruncatedbooleanrequired
    • timedOutbooleanrequired
    • startedAtstring<date-time>nullable
    • finishedAtstring<date-time>nullable
  • commandobject
    2 properties
    • idstringrequired

      Pass it to GET /v1/sandboxes/{sandboxId}/commands/{commandId}.

    • statusstringrequired
      One ofrunning
400Invalid body, or a test-mode key.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Sandbox not found, or it belongs to another project.
  • codestringrequired
  • messagestringrequired
  • detailsobject
409`sandbox_not_running`: the sandbox is stopped, stopping, failed or deleted; resume it first. `sandbox_not_ready`: it is still starting and did not become ready in time; retry.
  • codestringrequired
  • messagestringrequired
  • detailsobject
503`sandbox_unavailable`: no machine capacity right now. Nothing was charged for machine time; retry shortly.
  • codestringrequired
  • messagestringrequired
  • detailsobject