# Команды, процессы и терминалы

Выполнение с буферизацией подходит для коротких задач, чей полный вывод помещается в один ответ. Для постепенного вывода используйте SSE, для долговременного сервиса — фоновый процесс, а для интерактивной работы — браузерный терминал.

## Выполнение с буферизацией[​](#buffered-execution "Прямая ссылка на Выполнение с буферизацией")

`POST /v1/sandboxes/{id}/exec` ждет завершения и возвращает stdout, stderr и код выхода:

```
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/exec" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "cmd": "sh",
    "args": ["-lc", "printf \"working\\n\"; exit 0"],
    "cwd": "/tmp",
    "env": {"JOB_NAME": "demo"},
    "timeout": 30000
  }' |
  jq
```

Поля тела REST-запроса:

* `cmd` — строка с исполняемым файлом;
* `args` — массив аргументов;
* `cwd` — необязательная рабочая директория;
* `env` — дополнительные переменные команды;
* `timeout` — миллисекунды, по умолчанию пять минут;
* `user` — необязательное переопределение Unix-пользователя;
* `stdin` — необязательный base64-ввод для выполнения с буферизацией.

Имена полей REST и MCP различаются

MCP-инструмент `sandbox_exec` называет аргумент `timeout_ms` и переводит его в REST `timeout`. Не отправляйте старый массив `cmd` или `timeout_ms` прямо в REST-эндпоинт `/exec`.

HTTP `200` означает, что результат процесса получен. Всегда проверяйте `exit_code`: ненулевой код не превращается в HTTP-ошибку.

## SSE-стриминг[​](#stream-output-with-sse "Прямая ссылка на SSE-стриминг")

`POST /v1/sandboxes/{id}/exec-stream` принимает ту же команду, кроме `stdin`, и возвращает `text/event-stream`:

```
{"type":"stdout","text":"one line\n"}
{"type":"stderr","text":"warning\n"}
{"type":"exit","code":0}
```

Читайте поток до события `exit`. Эндпоинт явно отклоняет `stdin`.

## Фоновый процесс[​](#start-a-background-process "Прямая ссылка на Фоновый процесс")

`POST /v1/sandboxes/{id}/start` возвращает PID и HTTP `200`. Он подходит для сервиса, продолжающего работу после ответа. Затем можно отправить поддерживаемый сигнал через `/processes/{pid}/signal` или подключиться по WebSocket.

## Браузерный терминал[​](#use-the-browser-terminal "Прямая ссылка на Браузерный терминал")

Откройте активную песочницу и выберите *Терминал*. Надпись *Подключено* означает готовность интерактивной сессии. Используйте ее для TTY и состояния оболочки, а `/exec` — для автоматизации и детерминированного результата.

## Границы ошибок[​](#failure-boundaries "Прямая ссылка на Границы ошибок")

* Выполнение требует активной песочницы. Остановленной песочнице нужно возобновление, песочнице в гибернации — пробуждение.
* Таймаут команды и код выхода — разные сигналы.
* Команда идет от настроенного пользователя по умолчанию, обычно `user`; отдельный вызов может его переопределить.

## См. также[​](#related "Прямая ссылка на См. также")

* [Быстрый старт с API](/getting-started/api.md)
* [Жизненный цикл песочницы](/sandboxes/lifecycle.md)
* [Стриминг и обмен данными в реальном времени](/developers/streaming-and-realtime.md)
* [Протоколы песочницы для обмена данными в реальном времени](/api-reference/realtime.md)
* [Наблюдаемость и диагностика](/sandboxes/observability-and-troubleshooting.md)
