Skip to content

Commands

Run one-shot and interactive commands in a sandbox, with timeouts, signals, retries and exit codes.

Updated View as Markdown

A command is a list of arguments, run directly: there’s no shell unless you run one (sh -c '…'). It runs with the image’s environment, working directory and user unless you set env, workingDirectory or user. A command on a suspended sandbox resumes it first.

One-shot commands

Run a command answers with the command’s output as it arrives, then how it ended.

ezgh sandboxes exec scratch --workdir /work --env MODE=fast -- sh job.sh
timeoutSeconds 1 to 840; default 300. The command is ended when it runs out, and the answer says timedOut.
stdin At most 1 MiB, given with the request.
Answer exitCode, or signal when a signal ended it.

Over the API the answer is application/x-ndjson, one JSON object a line:

{"stream":"stdout","data":"NDIK"}
{"exitCode":0,"signal":null,"timedOut":false,"error":null}

data is base64. The last line is always the exit line. A command that needs longer than 840 seconds, or more input than 1 MiB, runs as an interactive command.

Interactive commands

An interactive command streams stdin to the command and its output back, for as long as it runs.

ezgh sandboxes exec -i scratch -- tar -xf - -C /work < work.tar
ezgh sandboxes exec -t scratch -- sh

-i streams stdin. -t adds a terminal, follows your window’s size, and implies -i.

Over the API it’s two calls: run a command with "interactive": true answers 201 with an execId, and you attach to it with a WebSocket.

Time to attach 30 seconds from the 201.
Attaches One, by whoever created the command.
Longest session 24 hours.
Terminal pty: true, with cols and rows from 1 to 1000.
Signals HUP, INT, QUIT, TERM, KILL, USR1, USR2, WINCH.

Binary messages carry one channel byte and then data: 0 is stdin from you, 1 is stdout and 2 is stderr to you. A message is at most 1 MiB. Text messages are JSON:

From Message
You {"type":"resize","cols":120,"rows":40}
You {"type":"signal","signal":"INT"}
You {"type":"stdinClose"}
The API {"type":"exit","exitCode":…,"signal":…,"code":…}, then it closes
The API {"type":"error","code":"…","message":"…"}, then it closes

stdin and timeoutSeconds are refused on an interactive command.

When a command is refused

Answer Means Do
409 sandbox_not_running The sandbox is stopped, failed or impaired. If it’s stopped, start it first.
503 sandbox_busy The sandbox is changing status. Send it again after Retry-After.
429 rate_limited Too many commands at once. See Limits. Send it again after Retry-After.

A refused command didn’t run, so sending it again is safe. A one-shot command whose connection drops after it was accepted may have run: the CLI doesn’t send it again.

An attach that’s refused has used its execId: create the command again and attach to the new one. An interactive command that ends with the error unavailable before you sent or received anything can be run again as a new command; the CLI does that once.

CLI exit codes

ezgh sandboxes exec exits with:

Exit code When
The command’s own The command exited.
128 + the signal’s number A signal ended the command.
124 The command timed out.

Anything else is ezgh’s usual exit code for an error.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close