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.shtimeoutSeconds |
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.