Skip to main content
POST
Run a command

Authorizations

Authorization
string
header
required

A team API key, sk_offstage_…, created in the console. Everything it touches belongs to its team.

Path Parameters

sandboxId
string
required

A sandbox id, sbx_….

Body

application/json

Unknown fields are refused with 400 unknown-field.

cmd
string
required

A shell command line, run as zsh -lc "<cmd>". Each command is a new process, so cd and export do not carry over; use cwd and envs. There is no stdin and no streaming output.

Required string length: 1 - 65536
cwd
string

The working directory, relative to the sandbox root (created if missing). The root by default. Same rules as a file path.

Required string length: 1 - 1024
Pattern: ^(?!/)(?!(.*/)?\.\.(/|$))[A-Za-z0-9._/-]+$
envs
object

Extra environment variables for this command only.

timeoutMs
integer
default:600000

10 minutes by default. Never past the sandbox's own end: the plane cuts it to what is left of the sandbox's life when the Mac takes the command, so lengthening the sandbox while the command waits for a place lengthens it too. A command already running keeps the end it started with. At the timeout the command's whole process tree is killed and the result has timedOut: true.

Required range: 1 <= x <= 1800000

Response

The command ended within the hold.

A command that ended. The fields after state are the Mac's own answer, relayed as it sent them.

commandId
string
required

cmd_….

Pattern: ^cmd_
state
any
required
exitCode
integer | null
required

Null when the command was killed at its timeout.

timedOut
boolean
required
stdout
string
required

The last 1 MiB of standard output. In a gui sandbox it carries both streams.

stderr
string
required

The last 1 MiB of standard error. Empty in a gui sandbox.

truncated
boolean
required

True when the start of a stream was dropped to keep its last 1 MiB.

durationMs
integer
required
Required range: x >= 0