---
title: "Commands"
description: "Run one-shot and interactive commands in a sandbox, with timeouts, signals, retries and exit codes."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

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](/sandboxes-api/ExecCommand/) answers with the command's output as it
arrives, then how it ended.

```sh
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:

```json
{"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.

```sh
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](/sandboxes-api/ExecCommand/) with
`"interactive": true` answers `201` with an `execId`, and you
[attach](/sandboxes-api/AttachExec/) 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](/sandboxes/limits#rates). | 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.

Source: https://docs.ezghcloud.com/sandboxes/commands/index.mdx
